@aitne/daemon 0.1.8 → 0.1.10

package/dist/services/browser-history/managed-chromium/instance-a-config.d.ts

@@ -0,0 +1,116 @@
+/**
+ * Pure flag / argv builder for Instance A (automation Chromium).
+ *
+ * MANAGED_CHROMIUM_IMPLEMENTATION_PLAN.md §5.2, §8.1.
+ *
+ * Instance A and Instance S share the same Chromium binary but never
+ * the same `--user-data-dir`. The structural differences from
+ * Instance S's `supervisor-config.ts:SHARED_FLAGS` are:
+ *
+ *   - `--remote-debugging-port=<random>` (CDP **enabled**). Instance S
+ *     uses `--remote-debugging-port=0` (disabled) because Playwright
+ *     must never touch the sync profile.
+ *   - `--remote-allow-origins=http://127.0.0.1:<port>` is NOT
+ *     needed for `connectOverCDP` (the daemon is the only consumer);
+ *     including it would silently widen the local-CDP surface.
+ *   - Per-workflow `--user-data-dir=<paDataDir>/chromium-automation-anon/<wfid>`.
+ *   - `--no-sandbox` is **not** added here. On macOS ≤ 25 / Linux /
+ *     Windows it is genuinely never added — the OS-level sandbox
+ *     primitive is the outer ring and Chromium's helper-process
+ *     renderer sandbox stays as the middle ring. On macOS 26+ the
+ *     launcher (`sandbox-launcher.ts:buildSandboxExecArgs`) injects
+ *     `--no-sandbox` itself when both the sandbox primitive is
+ *     `sandbox-exec` and `darwinTahoeOrLater()` is true, because
+ *     Tahoe's `forbidden-sandbox-reinit` default-deny makes the
+ *     middle ring fail unconditionally; the outer + inner rings
+ *     remain in force. Keeping the injection at the launcher rather
+ *     than this builder means an operator who chooses
+ *     `SandboxPrimitive.kind === "none"` (no outer ring) still gets
+ *     Chromium's middle ring as the only line of defence.
+ *
+ * Kept as a pure helper so the 100% coverage gate locks in:
+ *   - the CDP port flag's exact shape (a typo would silently disable
+ *     interception when Playwright's regex match fails)
+ *   - the headless flag is always present (a workflow that flips on a
+ *     window would leak desktop surface to the user)
+ *   - per-workflow profile dir is the LAST positional arg, so the
+ *     sandbox's writable-binding list lines up with Chromium's view
+ */
+/** Shared automation flags — applied verbatim on every Instance A
+ *  launch regardless of variant (anon / auth / purchase). */
+export declare const INSTANCE_A_SHARED_FLAGS: readonly string[];
+/** Per-workflow anon profile dir: `<PA_DATA_DIR>/chromium-automation-anon/<workflowId>`. */
+export declare function anonProfileDir(paDataDir: string, workflowId: string): string;
+export interface InstanceALaunchArgsInput {
+    paDataDir: string;
+    workflowId: string;
+    /** Loopback TCP port the daemon picks (cf. instance-a-launcher's
+     *  random-port helper). Caller ensures it's available before passing. */
+    cdpPort: number;
+}
+/**
+ * Build the full argv for a Chromium spawn under Instance A's anon
+ * variant. The launcher wraps this in the OS sandbox primitive and
+ * passes the binary path separately.
+ */
+export declare function buildInstanceAAnonArgs(input: InstanceALaunchArgsInput): readonly string[];
+/**
+ * Per-site auth profile dir:
+ * `<PA_DATA_DIR>/chromium-automation-auth/<siteKey>`.
+ *
+ * Throws on an invalid `siteKey` so a registry typo cannot land on disk
+ * as a directory at `~/.personal-agent/chromium-automation-auth/../etc`.
+ * The site registry validator already runs this check at module load;
+ * doing it again here is the defence-in-depth path-shape contract for
+ * any code path that builds an auth profile dir.
+ */
+export declare function authProfileDir(paDataDir: string, siteKey: string): string;
+export interface InstanceAAuthLaunchArgsInput {
+    paDataDir: string;
+    siteKey: string;
+    /** Loopback TCP port the daemon picks (cf. instance-a-launcher's
+     *  random-port helper). Caller ensures it's available before passing. */
+    cdpPort: number;
+}
+/**
+ * Build the full argv for a Chromium spawn under Instance A's auth
+ * variant — headless, reuses the per-site profile dir so persistent
+ * cookies survive across workflows. The launcher wraps this in the OS
+ * sandbox primitive and passes the binary path separately.
+ *
+ * Distinct from `buildInstanceAAuthBootstrapArgs` (in
+ * `supervisor-config.ts`), which builds the UI-shaped argv for the
+ * one-time sign-in window. The headless argv here is the per-workflow
+ * runtime shape — both must point at the same profile dir so cookies
+ * planted during sign-in are visible to subsequent workflow runs.
+ */
+export declare function buildInstanceAAuthArgs(input: InstanceAAuthLaunchArgsInput): readonly string[];
+/**
+ * Per-site purchase profile dir:
+ * `<PA_DATA_DIR>/chromium-automation-purchase/<siteKey>`.
+ *
+ * Strictly isolated from the auth profile dir of the same `siteKey`
+ * (different parent directory) — cookies / localStorage planted under
+ * B-2.5 sign-in cannot cross-contaminate the purchase profile, and the
+ * absolute-block layer's `chromium-automation-purchase/**` Read/Write
+ * deny patterns scope exactly to this tree.
+ *
+ * Throws on an invalid `siteKey` for the same reason as
+ * `authProfileDir` — a registry typo cannot land at
+ * `~/.personal-agent/chromium-automation-purchase/../etc`.
+ */
+export declare function purchaseProfileDir(paDataDir: string, siteKey: string): string;
+export interface InstanceAPurchaseLaunchArgsInput {
+    paDataDir: string;
+    siteKey: string;
+    cdpPort: number;
+}
+/**
+ * Build the full argv for a Chromium spawn under Instance A's purchase
+ * variant. Identical shape to the auth variant — headless, per-site
+ * profile dir — but rooted under `chromium-automation-purchase/` so
+ * the absolute-block layer + the file-shape guards distinguish the two
+ * trees. Plan §17.5: "operates on the A-purchase/<site_key> profile's
+ * already-populated cart".
+ */
+export declare function buildInstanceAPurchaseArgs(input: InstanceAPurchaseLaunchArgsInput): readonly string[];

package/dist/services/browser-history/managed-chromium/instance-a-config.js

@@ -0,0 +1,164 @@
+/**
+ * Pure flag / argv builder for Instance A (automation Chromium).
+ *
+ * MANAGED_CHROMIUM_IMPLEMENTATION_PLAN.md §5.2, §8.1.
+ *
+ * Instance A and Instance S share the same Chromium binary but never
+ * the same `--user-data-dir`. The structural differences from
+ * Instance S's `supervisor-config.ts:SHARED_FLAGS` are:
+ *
+ *   - `--remote-debugging-port=<random>` (CDP **enabled**). Instance S
+ *     uses `--remote-debugging-port=0` (disabled) because Playwright
+ *     must never touch the sync profile.
+ *   - `--remote-allow-origins=http://127.0.0.1:<port>` is NOT
+ *     needed for `connectOverCDP` (the daemon is the only consumer);
+ *     including it would silently widen the local-CDP surface.
+ *   - Per-workflow `--user-data-dir=<paDataDir>/chromium-automation-anon/<wfid>`.
+ *   - `--no-sandbox` is **not** added here. On macOS ≤ 25 / Linux /
+ *     Windows it is genuinely never added — the OS-level sandbox
+ *     primitive is the outer ring and Chromium's helper-process
+ *     renderer sandbox stays as the middle ring. On macOS 26+ the
+ *     launcher (`sandbox-launcher.ts:buildSandboxExecArgs`) injects
+ *     `--no-sandbox` itself when both the sandbox primitive is
+ *     `sandbox-exec` and `darwinTahoeOrLater()` is true, because
+ *     Tahoe's `forbidden-sandbox-reinit` default-deny makes the
+ *     middle ring fail unconditionally; the outer + inner rings
+ *     remain in force. Keeping the injection at the launcher rather
+ *     than this builder means an operator who chooses
+ *     `SandboxPrimitive.kind === "none"` (no outer ring) still gets
+ *     Chromium's middle ring as the only line of defence.
+ *
+ * Kept as a pure helper so the 100% coverage gate locks in:
+ *   - the CDP port flag's exact shape (a typo would silently disable
+ *     interception when Playwright's regex match fails)
+ *   - the headless flag is always present (a workflow that flips on a
+ *     window would leak desktop surface to the user)
+ *   - per-workflow profile dir is the LAST positional arg, so the
+ *     sandbox's writable-binding list lines up with Chromium's view
+ */
+import { join } from "node:path";
+import { INSTANCE_A_ANON_DIRNAME, INSTANCE_A_AUTH_DIRNAME, INSTANCE_A_PURCHASE_DIRNAME, } from "./types.js";
+/** Stable site-key shape — mirrors `automation/site-registry.ts:SITE_KEY_REGEX`.
+ *  Re-declared here so the path builder fails fast when an unsafe key
+ *  (containing `/`, `..`, NUL, whitespace) would otherwise escape the
+ *  profile-dir root and write into an arbitrary location. The registry
+ *  validator enforces this for shipping entries; this is the
+ *  defence-in-depth path-shape check the launcher runs unconditionally. */
+const SITE_KEY_REGEX = /^[a-z][a-z0-9_]*$/;
+/** Shared automation flags — applied verbatim on every Instance A
+ *  launch regardless of variant (anon / auth / purchase). */
+export const INSTANCE_A_SHARED_FLAGS = Object.freeze([
+    "--headless=new",
+    // Telemetry / autofill / translation / media-router off — Instance A
+    // exists for headless workflow execution, none of these are useful and
+    // each is a network-talkative surface.
+    "--disable-extensions",
+    "--disable-plugins",
+    "--disable-default-apps",
+    "--disable-component-update",
+    "--no-first-run",
+    "--no-default-browser-check",
+    "--no-experiments",
+    "--disable-features=AutofillServerCommunication,Translate,MediaRouter,InterestFeedV2",
+    // Off-the-record-style data minimisation — every workflow gets a
+    // fresh BrowserContext but these flags make the SingletonLock and
+    // per-profile crash dumps quieter when the dir is short-lived.
+    "--disable-crash-reporter",
+    "--disable-breakpad",
+    // Bind only to loopback for CDP. Chromium defaults to this when
+    // `--remote-debugging-port` is set, but stating it explicitly removes
+    // the chance of an environment-variable accidentally widening the
+    // bind. (`--remote-debugging-address=0.0.0.0` is a known agent-bypass
+    // shape; without the explicit flag a buggy operator override is the
+    // only way it could land, but defence-in-depth is cheap here.)
+    "--remote-debugging-address=127.0.0.1",
+]);
+/** Per-workflow anon profile dir: `<PA_DATA_DIR>/chromium-automation-anon/<workflowId>`. */
+export function anonProfileDir(paDataDir, workflowId) {
+    return join(paDataDir, INSTANCE_A_ANON_DIRNAME, workflowId);
+}
+/**
+ * Build the full argv for a Chromium spawn under Instance A's anon
+ * variant. The launcher wraps this in the OS sandbox primitive and
+ * passes the binary path separately.
+ */
+export function buildInstanceAAnonArgs(input) {
+    const profileDir = anonProfileDir(input.paDataDir, input.workflowId);
+    return Object.freeze([
+        ...INSTANCE_A_SHARED_FLAGS,
+        `--remote-debugging-port=${input.cdpPort}`,
+        `--user-data-dir=${profileDir}`,
+    ]);
+}
+/**
+ * Per-site auth profile dir:
+ * `<PA_DATA_DIR>/chromium-automation-auth/<siteKey>`.
+ *
+ * Throws on an invalid `siteKey` so a registry typo cannot land on disk
+ * as a directory at `~/.personal-agent/chromium-automation-auth/../etc`.
+ * The site registry validator already runs this check at module load;
+ * doing it again here is the defence-in-depth path-shape contract for
+ * any code path that builds an auth profile dir.
+ */
+export function authProfileDir(paDataDir, siteKey) {
+    if (!SITE_KEY_REGEX.test(siteKey)) {
+        throw new Error(`authProfileDir: siteKey "${siteKey}" violates naming convention`);
+    }
+    return join(paDataDir, INSTANCE_A_AUTH_DIRNAME, siteKey);
+}
+/**
+ * Build the full argv for a Chromium spawn under Instance A's auth
+ * variant — headless, reuses the per-site profile dir so persistent
+ * cookies survive across workflows. The launcher wraps this in the OS
+ * sandbox primitive and passes the binary path separately.
+ *
+ * Distinct from `buildInstanceAAuthBootstrapArgs` (in
+ * `supervisor-config.ts`), which builds the UI-shaped argv for the
+ * one-time sign-in window. The headless argv here is the per-workflow
+ * runtime shape — both must point at the same profile dir so cookies
+ * planted during sign-in are visible to subsequent workflow runs.
+ */
+export function buildInstanceAAuthArgs(input) {
+    const profileDir = authProfileDir(input.paDataDir, input.siteKey);
+    return Object.freeze([
+        ...INSTANCE_A_SHARED_FLAGS,
+        `--remote-debugging-port=${input.cdpPort}`,
+        `--user-data-dir=${profileDir}`,
+    ]);
+}
+/**
+ * Per-site purchase profile dir:
+ * `<PA_DATA_DIR>/chromium-automation-purchase/<siteKey>`.
+ *
+ * Strictly isolated from the auth profile dir of the same `siteKey`
+ * (different parent directory) — cookies / localStorage planted under
+ * B-2.5 sign-in cannot cross-contaminate the purchase profile, and the
+ * absolute-block layer's `chromium-automation-purchase/**` Read/Write
+ * deny patterns scope exactly to this tree.
+ *
+ * Throws on an invalid `siteKey` for the same reason as
+ * `authProfileDir` — a registry typo cannot land at
+ * `~/.personal-agent/chromium-automation-purchase/../etc`.
+ */
+export function purchaseProfileDir(paDataDir, siteKey) {
+    if (!SITE_KEY_REGEX.test(siteKey)) {
+        throw new Error(`purchaseProfileDir: siteKey "${siteKey}" violates naming convention`);
+    }
+    return join(paDataDir, INSTANCE_A_PURCHASE_DIRNAME, siteKey);
+}
+/**
+ * Build the full argv for a Chromium spawn under Instance A's purchase
+ * variant. Identical shape to the auth variant — headless, per-site
+ * profile dir — but rooted under `chromium-automation-purchase/` so
+ * the absolute-block layer + the file-shape guards distinguish the two
+ * trees. Plan §17.5: "operates on the A-purchase/<site_key> profile's
+ * already-populated cart".
+ */
+export function buildInstanceAPurchaseArgs(input) {
+    const profileDir = purchaseProfileDir(input.paDataDir, input.siteKey);
+    return Object.freeze([
+        ...INSTANCE_A_SHARED_FLAGS,
+        `--remote-debugging-port=${input.cdpPort}`,
+        `--user-data-dir=${profileDir}`,
+    ]);
+}

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

@@ -0,0 +1,82 @@
+/**
+ * Instance A on-demand launcher.
+ *
+ * MANAGED_CHROMIUM_IMPLEMENTATION_PLAN.md §8.1.
+ *
+ * Cold-start every workflow at MVP. Per-workflow profile dirs are
+ * incompatible with browser-process pooling (`--user-data-dir` is a
+ * launch-time flag) and the failure-mode coupling argument in §8.1
+ * makes pooling undesirable even with the cold-start latency cost.
+ *
+ * Flow:
+ *   1. Pick a free loopback TCP port (kernel-assigned via a transient
+ *      `net.Server.listen(0)`).
+ *   2. Materialise the sandbox primitive (per-OS — handled by the
+ *      shared `materialiseSandboxPrimitive` helper).
+ *   3. Spawn Chromium with `--remote-debugging-port=<port>` under the
+ *      sandbox primitive. Bindings:
+ *        - readable: Chromium binary path
+ *        - writable: per-workflow profile dir
+ *   4. Poll `GET http://127.0.0.1:<port>/json/version` every 200 ms
+ *      until CDP responds or the 5 s deadline elapses.
+ *   5. Hand back a `LaunchedInstanceA` carrying the port + a release
+ *      function that SIGTERMs (5 s grace) → SIGKILLs the Chromium PID
+ *      and (for the anon variant) deletes the profile dir.
+ *
+ * Concurrency cap of 1 instance globally is enforced at the workflow
+ * runner level — the runner takes a semaphore before calling this
+ * launcher so two concurrent workflows do not race on profile-dir
+ * creation.
+ *
+ * Excluded from the 100% coverage gate — every function in this module
+ * touches a real subprocess, the network, or the filesystem; matches the
+ * existing `chromium-launcher.ts` / `setup-bootstrap.ts` exclusion
+ * rationale.
+ */
+import type Database from "better-sqlite3";
+import type { HostProfile, SandboxPrimitive } from "../types.js";
+export type LaunchInstanceAOptions = {
+    db: Database.Database;
+    host: HostProfile;
+    paDataDir: string;
+    workflowId: string;
+    variant: "anon";
+} | {
+    db: Database.Database;
+    host: HostProfile;
+    paDataDir: string;
+    workflowId: string;
+    variant: "auth";
+    /** B-2.5 per-site profile dir identifier. */
+    siteKey: string;
+} | {
+    db: Database.Database;
+    host: HostProfile;
+    paDataDir: string;
+    workflowId: string;
+    variant: "purchase";
+    /** B-4 per-site profile dir identifier. Strictly isolated from
+     *  the auth profile of the same siteKey — different parent
+     *  directory under PA_DATA_DIR. */
+    siteKey: string;
+};
+export interface LaunchedInstanceA {
+    cdpPort: number;
+    cdpEndpoint: string;
+    /** Profile dir on disk — release() deletes it for anon variants
+     *  and preserves it for auth (per-site cookies must persist across
+     *  workflow runs). */
+    profileDir: string;
+    /** Tear down: close any sockets, SIGTERM Chromium. For the anon
+     *  variant, also deletes the per-workflow profile dir. Idempotent. */
+    release(): Promise<void>;
+}
+export type LaunchInstanceAResult = {
+    ok: true;
+    handle: LaunchedInstanceA;
+} | {
+    ok: false;
+    reason: "missing_binary" | "missing_sandbox" | "spawn_failed" | "cdp_timeout";
+};
+export declare function launchInstanceA(opts: LaunchInstanceAOptions): Promise<LaunchInstanceAResult>;
+export type { SandboxPrimitive };

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

@@ -0,0 +1,200 @@
+/**
+ * Instance A on-demand launcher.
+ *
+ * MANAGED_CHROMIUM_IMPLEMENTATION_PLAN.md §8.1.
+ *
+ * Cold-start every workflow at MVP. Per-workflow profile dirs are
+ * incompatible with browser-process pooling (`--user-data-dir` is a
+ * launch-time flag) and the failure-mode coupling argument in §8.1
+ * makes pooling undesirable even with the cold-start latency cost.
+ *
+ * Flow:
+ *   1. Pick a free loopback TCP port (kernel-assigned via a transient
+ *      `net.Server.listen(0)`).
+ *   2. Materialise the sandbox primitive (per-OS — handled by the
+ *      shared `materialiseSandboxPrimitive` helper).
+ *   3. Spawn Chromium with `--remote-debugging-port=<port>` under the
+ *      sandbox primitive. Bindings:
+ *        - readable: Chromium binary path
+ *        - writable: per-workflow profile dir
+ *   4. Poll `GET http://127.0.0.1:<port>/json/version` every 200 ms
+ *      until CDP responds or the 5 s deadline elapses.
+ *   5. Hand back a `LaunchedInstanceA` carrying the port + a release
+ *      function that SIGTERMs (5 s grace) → SIGKILLs the Chromium PID
+ *      and (for the anon variant) deletes the profile dir.
+ *
+ * Concurrency cap of 1 instance globally is enforced at the workflow
+ * runner level — the runner takes a semaphore before calling this
+ * launcher so two concurrent workflows do not race on profile-dir
+ * creation.
+ *
+ * Excluded from the 100% coverage gate — every function in this module
+ * touches a real subprocess, the network, or the filesystem; matches the
+ * existing `chromium-launcher.ts` / `setup-bootstrap.ts` exclusion
+ * rationale.
+ */
+import { mkdir, rm } from "node:fs/promises";
+import { createServer } from "node:net";
+import { setTimeout as delay } from "node:timers/promises";
+import { createLogger } from "../../../logging.js";
+import { anonProfileDir, authProfileDir, buildInstanceAAnonArgs, buildInstanceAAuthArgs, buildInstanceAPurchaseArgs, purchaseProfileDir, } from "./instance-a-config.js";
+import { launchUnderSandbox } from "./sandbox-launcher.js";
+import { materialiseSandboxPrimitive } from "./sandbox-install.js";
+import { chromiumBundleRoot } from "../lifecycle/platform.js";
+const logger = createLogger("instance-a-launcher");
+/** Hard ceiling on the spawn-to-CDP-ready window. Chromium under
+ *  sandbox-exec / bwrap typically responds in ~1.5–2 s; 5 s is a
+ *  generous slack for cold storage / lower-tier machines. */
+const CDP_READY_TIMEOUT_MS = 5000;
+const CDP_READY_POLL_INTERVAL_MS = 200;
+const SIGTERM_GRACE_MS = 5000;
+export async function launchInstanceA(opts) {
+    const binaryPath = opts.host.browserBinaryFor("chromium");
+    if (!binaryPath) {
+        return { ok: false, reason: "missing_binary" };
+    }
+    if (opts.host.sandboxPrimitive.kind === "none") {
+        // Mirror Instance S's gate — operator must explicitly opt-in to
+        // unsandboxed via the dashboard's `enable` flow. The runner reads
+        // the per-install opt-in flag and refuses to call this launcher
+        // without it; this is the defence-in-depth refusal.
+        return { ok: false, reason: "missing_sandbox" };
+    }
+    const profileDir = opts.variant === "anon"
+        ? anonProfileDir(opts.paDataDir, opts.workflowId)
+        : opts.variant === "auth"
+            ? authProfileDir(opts.paDataDir, opts.siteKey)
+            : purchaseProfileDir(opts.paDataDir, opts.siteKey);
+    await mkdir(profileDir, { recursive: true });
+    const cdpPort = await pickFreeLoopbackPort();
+    const sandbox = await materialiseSandboxPrimitive(opts.host.sandboxPrimitive, {
+        paDataDir: opts.paDataDir,
+        binaryPath,
+        userDataDir: profileDir,
+    });
+    const args = opts.variant === "anon"
+        ? buildInstanceAAnonArgs({
+            paDataDir: opts.paDataDir,
+            workflowId: opts.workflowId,
+            cdpPort,
+        })
+        : opts.variant === "auth"
+            ? buildInstanceAAuthArgs({
+                paDataDir: opts.paDataDir,
+                siteKey: opts.siteKey,
+                cdpPort,
+            })
+            : buildInstanceAPurchaseArgs({
+                paDataDir: opts.paDataDir,
+                siteKey: opts.siteKey,
+                cdpPort,
+            });
+    // On spawn / CDP failure, the anon path nukes the per-workflow
+    // profile dir (it would only collect garbage otherwise). The auth
+    // and purchase paths MUST NOT — the per-site cookies are the entire
+    // reason the bootstrap dance exists; deleting them on a transient
+    // spawn failure would silently invalidate the user's sign-in and
+    // look like a re-auth requirement on the next workflow.
+    const cleanupOnFailure = async () => {
+        if (opts.variant === "anon") {
+            await rm(profileDir, { recursive: true, force: true }).catch(() => { });
+        }
+    };
+    let child;
+    try {
+        const result = launchUnderSandbox(sandbox, {
+            binary: binaryPath,
+            args,
+            readableBindings: [chromiumBundleRoot(binaryPath)],
+            writableBindings: [profileDir],
+            detached: false,
+        });
+        child = result.child;
+    }
+    catch (err) {
+        logger.error({ err, workflowId: opts.workflowId }, "Instance A spawn failed");
+        await cleanupOnFailure();
+        return { ok: false, reason: "spawn_failed" };
+    }
+    if (!child.pid) {
+        await cleanupOnFailure();
+        return { ok: false, reason: "spawn_failed" };
+    }
+    const pid = child.pid;
+    const ready = await waitForCdpReady(`http://127.0.0.1:${cdpPort}`, CDP_READY_TIMEOUT_MS);
+    if (!ready) {
+        logger.warn({ pid, workflowId: opts.workflowId }, "Instance A CDP ready timeout");
+        await opts.host.terminate(pid, "force").catch(() => { });
+        await cleanupOnFailure();
+        return { ok: false, reason: "cdp_timeout" };
+    }
+    let released = false;
+    const handle = {
+        cdpPort,
+        cdpEndpoint: `http://127.0.0.1:${cdpPort}`,
+        profileDir,
+        async release() {
+            if (released)
+                return;
+            released = true;
+            try {
+                await opts.host.terminate(pid, "graceful");
+                await delay(SIGTERM_GRACE_MS);
+            }
+            catch {
+                // best-effort
+            }
+            await opts.host.terminate(pid, "force").catch(() => { });
+            if (opts.variant === "anon") {
+                await rm(profileDir, { recursive: true, force: true }).catch((err) => {
+                    logger.warn({ err, profileDir, workflowId: opts.workflowId }, "Instance A anon profile cleanup failed (will retry at next launch)");
+                });
+            }
+        },
+    };
+    return { ok: true, handle };
+}
+/** Bind to port 0 on loopback, read back the kernel-assigned port,
+ *  close. Has a small TOCTOU window before Chromium grabs the port —
+ *  not exploitable from outside the loopback interface and the CDP
+ *  layer would simply fail to start if a parallel process grabbed it
+ *  in that window, which we surface as `cdp_timeout`. */
+async function pickFreeLoopbackPort() {
+    return new Promise((resolve, reject) => {
+        const server = createServer();
+        server.unref();
+        server.on("error", reject);
+        server.listen({ port: 0, host: "127.0.0.1" }, () => {
+            const address = server.address();
+            if (typeof address === "object" && address && "port" in address) {
+                const port = address.port;
+                server.close(() => resolve(port));
+            }
+            else {
+                server.close();
+                reject(new Error("failed to read kernel-assigned port"));
+            }
+        });
+    });
+}
+/** Poll `<endpoint>/json/version` until it responds with a 2xx or the
+ *  deadline elapses. The CDP HTTP endpoint is available before the
+ *  WebSocket upgrade, so a 2xx here is the canonical readiness signal. */
+async function waitForCdpReady(endpoint, deadlineMs) {
+    const deadlineAt = Date.now() + deadlineMs;
+    while (Date.now() < deadlineAt) {
+        try {
+            const ac = new AbortController();
+            const timer = setTimeout(() => ac.abort(), 500).unref();
+            const res = await fetch(`${endpoint}/json/version`, { signal: ac.signal });
+            clearTimeout(timer);
+            if (res.ok)
+                return true;
+        }
+        catch {
+            // not ready yet
+        }
+        await delay(CDP_READY_POLL_INTERVAL_MS);
+    }
+    return false;
+}

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

@@ -0,0 +1,69 @@
+/**
+ * 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 type Database from "better-sqlite3";
+import type { Observer } from "../../../observers/manager.js";
+import type { MessageHub } from "../../../adapters/message-hub.js";
+import type { BrowserProfileCandidate, HostProfile } from "../types.js";
+import { launchUnderSandbox } from "./sandbox-launcher.js";
+import { materialiseSandboxPrimitive } from "./sandbox-install.js";
+export interface ManagedChromiumSupervisorDeps {
+    db: Database.Database;
+    paDataDir: string;
+    host?: HostProfile;
+    messageHub?: MessageHub | null;
+    /** Test hook: clock. */
+    now?: () => number;
+    /** Test hook: launcher. */
+    launcher?: typeof launchUnderSandbox;
+    /** Test hook: sandbox resolver. */
+    resolveSandbox?: typeof materialiseSandboxPrimitive;
+    /** Optional cycle interval override (minutes). */
+    checkIntervalMinutes?: number;
+}
+export declare class ManagedChromiumSupervisor implements Observer {
+    private readonly deps;
+    readonly name = "managed-chromium-supervisor";
+    private timer;
+    private running;
+    private tickInFlight;
+    constructor(deps: ManagedChromiumSupervisorDeps);
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    /** Public for testing — runs a single supervisor cycle. */
+    tick(): Promise<void>;
+    private cycleOnce;
+    private applyReauthResult;
+    private applyOutcome;
+    private sendBrokenSyncDm;
+    private recordTelemetry;
+    private recordReauthAudit;
+}
+/**
+ * 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.
+ */
+declare function pseudoProfileCandidate(binaryPath: string, userDataDir: string): BrowserProfileCandidate;
+export declare const __testing: {
+    pseudoProfileCandidate: typeof pseudoProfileCandidate;
+    DM_TEMPLATES: Record<"sync_silent" | "account_changed" | "corrupt_local_state" | "signed_out", (detail: string | undefined) => string>;
+};
+export {};