@speedkit/cli 4.20.2 → 4.20.4

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+## [4.20.4](https://gitlab.orestes.info/baqend/speed-kit-cli/compare/v4.20.3...v4.20.4) (2026-08-10)
+
+
+### Bug Fixes
+
+* **onboarding:** detect and repair deployed service worker takeovers ([6d61ae7](https://gitlab.orestes.info/baqend/speed-kit-cli/commit/6d61ae71bab7dc2bbd4926d0c17fc8505d7f523e))
+
+## [4.20.3](https://gitlab.orestes.info/baqend/speed-kit-cli/compare/v4.20.2...v4.20.3) (2026-08-07)
+
+
+### Bug Fixes
+
+* **onboarding:** make headless launch match headed ([aa9af3e](https://gitlab.orestes.info/baqend/speed-kit-cli/commit/aa9af3ea69602c82ef30ffa547b33a32092258e5))
+
 ## [4.20.2](https://gitlab.orestes.info/baqend/speed-kit-cli/compare/v4.20.1...v4.20.2) (2026-08-07)
 
 

package/README.md

@@ -21,7 +21,7 @@ $ npm install -g @speedkit/cli
 $ sk COMMAND
 running command...
 $ sk (--version)
-@speedkit/cli/4.20.2 linux-x64 node-v22.23.2
+@speedkit/cli/4.20.4 linux-x64 node-v22.23.2
 $ sk --help [COMMAND]
 USAGE
   $ sk COMMAND

package/dist/services/onboarding/browser/baqend-response.js

@@ -1,3 +1,12 @@
+/**
+ * Makes a value safe for Fetch.fulfillRequest: collapse line breaks and strip
+ * characters outside latin-1, either of which Chrome rejects as "Invalid header".
+ */
+function sanitizeHeaderValue(value) {
+    return String(value)
+        .replace(/[\r\n]+/g, " ")
+        .replace(/[^\x20-\xff\t]/g, "?");
+}
 const DEFAULT_HEADERS = [
     { name: "Date", value: new Date().toUTCString() },
     { name: "Content-Encoding", value: "identity" },
@@ -24,19 +33,28 @@ export class BaqendResponse {
             : Buffer.from(body).toString("base64");
     }
     setHeader(name, value) {
+        const sanitized = sanitizeHeaderValue(value);
         for (const header of this.responseHeaders) {
             if (header.name === name) {
-                header.value = value;
+                header.value = sanitized;
                 return;
             }
         }
-        this.responseHeaders.push({ name, value });
+        this.responseHeaders.push({ name, value: sanitized });
     }
     addCustomHeaders(headers) {
+        // Fetch.fulfillRequest rejects header values with line breaks or
+        // non-latin-1 characters ("Invalid header") — e.g. an error message with
+        // a newline placed into x-error left the request hanging in paused state.
+        for (const header of headers) {
+            header.value = sanitizeHeaderValue(header.value);
+        }
         if (!headers?.find((o) => o.name === "Cache-Control")) {
             headers.push({
                 name: "Cache-Control",
-                value: "max-age=0, nocache, nostore",
+                // NOTE: was "nocache, nostore" — invalid directive names that browsers
+                // ignore, leaving locally served responses cacheable.
+                value: "max-age=0, no-cache, no-store",
             });
         }
         const origin = headers?.find((o) => o.name.toLowerCase() === "origin")?.value;

package/dist/services/onboarding/browser/executable/headed-user-agent.d.ts

@@ -0,0 +1,7 @@
+/**
+ * The user agent headed Chrome sends for this build. Headless would otherwise say
+ * `HeadlessChrome/<version>`, which some origins treat as a crawler.
+ *
+ * @param browserVersionString `chrome --version` output, e.g. `Google Chrome for Testing 146.0.7680.165`
+ */
+export declare function buildHeadedUserAgent(browserVersionString: string, platform?: string): string | undefined;

package/dist/services/onboarding/browser/executable/headed-user-agent.js

@@ -0,0 +1,29 @@
+/**
+ * Chrome's reduced User-Agent, as documented at https://www.chromium.org/updates/ua-reduction/:
+ *
+ *   Mozilla/5.0 (<unifiedPlatform>) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/<major>.0.0.0 Safari/537.36
+ *
+ * Only the major version moves — everything after it is frozen at 0.0.0, and the platform tokens are
+ * literal values that "will not update even if a user is on an updated operating system or device".
+ * So taking the major version from the installed binary keeps this current on its own.
+ */
+const UNIFIED_PLATFORMS = {
+    darwin: "Macintosh; Intel Mac OS X 10_15_7",
+    win32: "Windows NT 10.0; Win64; x64",
+};
+// Chrome reports X11 for every other *nix build it ships.
+const DEFAULT_UNIFIED_PLATFORM = "X11; Linux x86_64";
+/**
+ * The user agent headed Chrome sends for this build. Headless would otherwise say
+ * `HeadlessChrome/<version>`, which some origins treat as a crawler.
+ *
+ * @param browserVersionString `chrome --version` output, e.g. `Google Chrome for Testing 146.0.7680.165`
+ */
+export function buildHeadedUserAgent(browserVersionString, platform = process.platform) {
+    const majorVersion = browserVersionString.match(/(\d+)\.\d+\.\d+\.\d+/)?.[1];
+    if (!majorVersion) {
+        return undefined;
+    }
+    const unifiedPlatform = UNIFIED_PLATFORMS[platform] ?? DEFAULT_UNIFIED_PLATFORM;
+    return `Mozilla/5.0 (${unifiedPlatform}) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/${majorVersion}.0.0.0 Safari/537.36`;
+}

package/dist/services/onboarding/browser/executable/headed-user-agent.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/services/onboarding/browser/executable/headed-user-agent.spec.js

@@ -0,0 +1,30 @@
+import { expect } from "chai";
+import { describe, it } from "mocha";
+import { buildHeadedUserAgent } from "./headed-user-agent.js";
+const CHROME_VERSION = "Google Chrome for Testing 146.0.7680.165";
+describe("buildHeadedUserAgent", () => {
+    it("builds the reduced user agent for Linux", () => {
+        expect(buildHeadedUserAgent(CHROME_VERSION, "linux")).to.equal("Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/146.0.0.0 Safari/537.36");
+    });
+    it("builds the reduced user agent for macOS", () => {
+        expect(buildHeadedUserAgent(CHROME_VERSION, "darwin")).to.equal("Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/146.0.0.0 Safari/537.36");
+    });
+    it("builds the reduced user agent for Windows", () => {
+        expect(buildHeadedUserAgent(CHROME_VERSION, "win32")).to.equal("Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/146.0.0.0 Safari/537.36");
+    });
+    it("falls back to the X11 platform token on other unix builds", () => {
+        expect(buildHeadedUserAgent(CHROME_VERSION, "freebsd")).to.include("(X11; Linux x86_64)");
+    });
+    it("freezes everything after the major version", () => {
+        expect(buildHeadedUserAgent("Google Chrome 131.0.6778.86", "linux")).to.include("Chrome/131.0.0.0 ");
+    });
+    it("reads the version from the Windows ProductName + FileVersion shape", () => {
+        expect(buildHeadedUserAgent("Google Chrome 146.0.7680.165", "win32")).to.include("Chrome/146.0.0.0 ");
+    });
+    it("never advertises the headless token", () => {
+        expect(buildHeadedUserAgent(CHROME_VERSION, "linux")).to.not.include("HeadlessChrome");
+    });
+    it("returns undefined when the version string has no version in it", () => {
+        expect(buildHeadedUserAgent("unknown", "linux")).to.equal(undefined);
+    });
+});

package/dist/services/onboarding/fetch-event-handler.js

@@ -41,10 +41,17 @@ export class FetchEventHandler {
             if (response.errorObj) {
                 this.cli.writeError(`error on ${event.request.url}`);
                 this.cli.writeError(`${response.errorObj.message}`);
-                return;
             }
-            this.cli.writeError(`error on ${target.url()}`);
-            this.cli.writeError(JSON.stringify(response.errorObj));
+            else {
+                this.cli.writeError(`error on ${target.url()}`);
+                this.cli.writeError(JSON.stringify(response.errorObj));
+            }
+            // A request left in paused state hangs until the browser times out.
+            // Fail it explicitly so the page sees a network error instead.
+            await safe(cdpSession.send("Fetch.failRequest", {
+                requestId: event.requestId,
+                errorReason: "Failed",
+            }));
         });
     }
     canHandlePattern(fetchEventHandler, url, resourceType, requestStage) {

package/dist/services/onboarding/fetch-events/speed-kit-service-worker-js.d.ts

@@ -11,6 +11,14 @@ export declare class SpeedKitServiceWorkerJs implements FetchRequestPausedEventH
     private customerConfig;
     private serviceWorker;
     readonly patterns: Protocol.Fetch.RequestPattern[];
+    /**
+     * Timestamp of the last locally served sw.js. Chrome's SW update checker
+     * fetches scripts in the browser process, outside CDP Fetch interception —
+     * an update that slips through installs the DEPLOYED build. A SW version
+     * that activates without a recent local serve is such a takeover; the
+     * OnboardingService uses this timestamp to detect and repair it.
+     */
+    lastServedAt: number;
     constructor(customerConfig: CustomerConfig, serviceWorker: FileInterface);
     handle(): Promise<Partial<Protocol.Fetch.FulfillRequestRequest>>;
 }

package/dist/services/onboarding/fetch-events/speed-kit-service-worker-js.js

@@ -9,6 +9,14 @@ export class SpeedKitServiceWorkerJs {
     customerConfig;
     serviceWorker;
     patterns;
+    /**
+     * Timestamp of the last locally served sw.js. Chrome's SW update checker
+     * fetches scripts in the browser process, outside CDP Fetch interception —
+     * an update that slips through installs the DEPLOYED build. A SW version
+     * that activates without a recent local serve is such a takeover; the
+     * OnboardingService uses this timestamp to detect and repair it.
+     */
+    lastServedAt = 0;
     constructor(customerConfig, serviceWorker) {
         this.customerConfig = customerConfig;
         this.serviceWorker = serviceWorker;
@@ -20,6 +28,7 @@ export class SpeedKitServiceWorkerJs {
         ];
     }
     async handle() {
+        this.lastServedAt = Date.now();
         return new BaqendResponse(this.serviceWorker.getContent(), "text/javascript; charset=utf-8");
     }
 }

package/dist/services/onboarding/onboarding-model.d.ts

@@ -5,6 +5,8 @@ import { AbortResponse } from "./browser/abort-response.js";
 import { task } from "./todo-collector.js";
 import { VanillaPuppeteer } from "puppeteer-extra";
 import { Command } from "@oclif/core/command";
+declare const HEADLESS_DEFAULT_ARGS_TO_DROP: string[];
+export { HEADLESS_DEFAULT_ARGS_TO_DROP };
 export declare const BROWSER_EVENTS: {
     DISCONNECTED: string;
     FETCH_AUTH_REQUIRED: string;
@@ -14,6 +16,7 @@ export declare const CDP_SESSION: {
     EVENTS: {
         SERVICE_WORKER: {
             REGISTRATION_UPDATED: string;
+            VERSION_UPDATED: string;
         };
     };
     MESSAGE: {
@@ -43,6 +46,12 @@ export declare class BrowserContext {
     readonly browserArgs: string[];
     readonly chromePath: string;
     constructor(domain: string, browserVersionString?: string, chromeFlags?: string[], userConfig?: UserCliConfig, userAgent?: string, debuggingPort?: boolean, headless?: boolean, debugPort?: number);
+    /**
+     * Applied as a launch flag rather than over CDP on purpose: a per-page
+     * `Network.setUserAgentOverride` never reaches the Service Worker, so Speed Kit's dynamic-block
+     * refetch would still leak the headless token and re-poison the merged body.
+     */
+    private getHeadlessParityArgs;
     private isChromeBrowser;
     private getBrowserExtensionPath;
     getPuppeteerLaunchOptions(): Parameters<VanillaPuppeteer["launch"]>[0];

package/dist/services/onboarding/onboarding-model.js

@@ -1,6 +1,7 @@
 import { Flags } from "@oclif/core";
 import { CLI_CONFIG_IS_TEST, CLI_CONFIG_NAME, CLIParameters, CLIParametersChar, } from "../../models/cli-parameters.js";
 import { BrowserConfig } from "./browser/config/browser-config.js";
+import { buildHeadedUserAgent } from "./browser/executable/headed-user-agent.js";
 import { resolve } from "node:path";
 const DEFAULT_BROWSER_ARGS = [
     "--enable-features=Translate,NetworkService",
@@ -12,6 +13,25 @@ const DEFAULT_BROWSER_ARGS = [
     // triggered by the flag above. Value is arbitrary and only used as an identifier.
     "--test-type=speed-kit-cli",
 ];
+// Headless Chrome differs from headed in ways customer bot detection and responsive layout both
+// key on, so a page can render differently — or not at all — depending on the mode. Each entry
+// below erases one measured difference; see HEADLESS_DEFAULT_ARGS_TO_DROP for the counterpart.
+const HEADLESS_PARITY_ARGS = [
+    // Headless exposes no pointing device, so `hover: none` / `any-pointer: coarse` send sites down
+    // their touch code path.
+    "--blink-settings=primaryHoverType=2,availableHoverTypes=2,primaryPointerType=4,availablePointerTypes=4",
+    // Headless otherwise pins the screen to 800x600, i.e. a tablet breakpoint. --screen-info is what
+    // overrides it; Chrome's own --ozone-override-screen-size is not reachable via ignoreDefaultArgs.
+    "--window-size=1920,1200",
+    "--screen-info={1920x1200}",
+];
+// Puppeteer-injected headless defaults with no headed equivalent. ignoreDefaultArgs only filters what
+// Puppeteer itself adds, so a spec asserts every entry is still in its defaultArgs.
+const HEADLESS_DEFAULT_ARGS_TO_DROP = [
+    // Scrollbar width 0 instead of 15 narrows the layout viewport and skews layout-shift work.
+    "--hide-scrollbars",
+];
+export { HEADLESS_DEFAULT_ARGS_TO_DROP };
 export const BROWSER_EVENTS = {
     DISCONNECTED: "disconnected",
     FETCH_AUTH_REQUIRED: "Fetch.authRequired",
@@ -21,6 +41,7 @@ export const CDP_SESSION = {
     EVENTS: {
         SERVICE_WORKER: {
             REGISTRATION_UPDATED: "ServiceWorker.workerRegistrationUpdated",
+            VERSION_UPDATED: "ServiceWorker.workerVersionUpdated",
         },
     },
     MESSAGE: {
@@ -61,7 +82,8 @@ export class BrowserContext {
         this.domain = domain;
         this.chromeFlags = chromeFlags || [];
         this.chromePath = resolve(userConfig.chromePath);
-        const browserArguments = DEFAULT_BROWSER_ARGS;
+        // Copy: pushing onto the shared module-level array leaked args into every later instance.
+        const browserArguments = [...DEFAULT_BROWSER_ARGS];
         if (userConfig?.chromeUserProfilePath) {
             browserArguments.push(`--user-data-dir=${userConfig?.chromeUserProfilePath}`);
         }
@@ -70,12 +92,32 @@ export class BrowserContext {
             const temporaryProfileDirectory = browserConfig.loadProfileTempDir();
             browserArguments.push(`--user-data-dir=${temporaryProfileDirectory}`);
         }
+        if (this.headless) {
+            this.userAgent =
+                this.userAgent ?? buildHeadedUserAgent(browserVersionString);
+        }
         this.browserArgs = [
             ...browserArguments,
             `--unsafely-treat-insecure-origin-as-secure=${domain}`,
+            ...this.getHeadlessParityArgs(),
+            // Last, so a customer's chromeFlags override our defaults — Chrome takes the last occurrence.
             ...this.chromeFlags,
         ];
     }
+    /**
+     * Applied as a launch flag rather than over CDP on purpose: a per-page
+     * `Network.setUserAgentOverride` never reaches the Service Worker, so Speed Kit's dynamic-block
+     * refetch would still leak the headless token and re-poison the merged body.
+     */
+    getHeadlessParityArgs() {
+        if (!this.headless) {
+            return [];
+        }
+        return [
+            ...HEADLESS_PARITY_ARGS,
+            ...(this.userAgent ? [`--user-agent=${this.userAgent}`] : []),
+        ];
+    }
     isChromeBrowser() {
         return !!/chrome/i.test(this.browserVersionString);
     }
@@ -95,7 +137,10 @@ export class BrowserContext {
             args: this.browserArgs,
             // Strip Puppeteer's default `--enable-automation` so Chrome doesn't show
             // the "Chrome is being controlled by automated test software" infobar.
-            ignoreDefaultArgs: ["--enable-automation"],
+            ignoreDefaultArgs: [
+                "--enable-automation",
+                ...(this.headless ? HEADLESS_DEFAULT_ARGS_TO_DROP : []),
+            ],
         };
         if (this.userConfig?.chromeExtensionPaths) {
             if (this.isChromeBrowser()) {

package/dist/services/onboarding/onboarding-model.spec.js

@@ -1,12 +1,20 @@
 import { expect } from "chai";
 import { describe, it } from "mocha";
-import { BrowserContext } from "./onboarding-model.js";
+import { BrowserContext, HEADLESS_DEFAULT_ARGS_TO_DROP, } from "./onboarding-model.js";
+import { buildHeadedUserAgent } from "./browser/executable/headed-user-agent.js";
 // Providing chromeUserProfilePath keeps BrowserContext off the filesystem
 // (it skips the temp-profile branch in the constructor).
 const userConfig = {
     chromePath: "/usr/bin/google-chrome",
     chromeUserProfilePath: "/tmp/sk-test-profile",
 };
+function newContext(headless, { chromeFlags = [], userAgent, browserVersionString = "Google Chrome for Testing 146.0.7680.165", } = {}) {
+    return new BrowserContext("example.com", browserVersionString, chromeFlags, userConfig, userAgent, false, headless, undefined);
+}
+function launchArgs(headless, overrides = {}) {
+    return newContext(headless, overrides).getPuppeteerLaunchOptions()
+        .args;
+}
 function remoteDebuggingArg(debuggingPort, headless, debugPort) {
     const context = new BrowserContext("example.com", "Chrome/120", [], userConfig, undefined, debuggingPort, headless, debugPort);
     const args = context.getPuppeteerLaunchOptions().args;
@@ -26,3 +34,65 @@ describe("BrowserContext.getPuppeteerLaunchOptions remote debugging port", () =>
         expect(remoteDebuggingArg(false, false, 9223)).to.equal(undefined);
     });
 });
+describe("BrowserContext headless/headed parity", () => {
+    const userAgentOf = (args) => args.find((arg) => arg.startsWith("--user-agent="));
+    it("derives the headed user agent from the installed Chrome version", () => {
+        expect(userAgentOf(launchArgs(true))).to.equal(`--user-agent=${buildHeadedUserAgent("Google Chrome for Testing 146.0.7680.165")}`);
+    });
+    it("never contains the HeadlessChrome token", () => {
+        expect(launchArgs(true).join(" ")).to.not.include("HeadlessChrome");
+    });
+    it("leaves the user agent to Chrome in headed mode", () => {
+        expect(userAgentOf(launchArgs(false))).to.equal(undefined);
+    });
+    it("prefers an explicitly provided user agent", () => {
+        expect(userAgentOf(launchArgs(true, { userAgent: "custom-agent" }))).to.equal("--user-agent=custom-agent");
+    });
+    it("omits the flag when the Chrome version cannot be read", () => {
+        expect(userAgentOf(launchArgs(true, { browserVersionString: "unknown" }))).to.equal(undefined);
+    });
+    it("restores hover and fine-pointer support", () => {
+        expect(launchArgs(true)).to.include("--blink-settings=primaryHoverType=2,availableHoverTypes=2,primaryPointerType=4,availablePointerTypes=4");
+    });
+    it("overrides the 800x600 headless screen", () => {
+        expect(launchArgs(true)).to.include.members([
+            "--window-size=1920,1200",
+            "--screen-info={1920x1200}",
+        ]);
+    });
+    it("applies no parity args in headed mode", () => {
+        const headedArgs = launchArgs(false);
+        expect(headedArgs).to.not.include("--window-size=1920,1200");
+        expect(headedArgs.some((arg) => arg.startsWith("--blink-settings="))).to.equal(false);
+    });
+    it("lets customer chromeFlags win over the parity defaults", () => {
+        const args = launchArgs(true, {
+            chromeFlags: ["--window-size=390,844", "--user-agent=mobile-agent"],
+        });
+        // Chrome takes the last occurrence of a switch, so the customer values must come last.
+        expect(args.lastIndexOf("--window-size=390,844")).to.be.greaterThan(args.lastIndexOf("--window-size=1920,1200"));
+        expect(args.lastIndexOf("--user-agent=mobile-agent")).to.be.greaterThan(args.findIndex((arg) => arg.startsWith("--user-agent=Mozilla/5.0")));
+    });
+    it("drops the Puppeteer headless defaults that have no headed equivalent", () => {
+        expect(newContext(true).getPuppeteerLaunchOptions().ignoreDefaultArgs).to.include.members(["--enable-automation", "--hide-scrollbars"]);
+    });
+    // ignoreDefaultArgs filters Puppeteer's own args by exact string. Anything Chrome adds itself is
+    // unreachable that way, and a Puppeteer bump that renames or drops an arg would silently turn an
+    // entry into a no-op — which is how --ozone-override-screen-size got in here in the first place.
+    it("only ignores args Puppeteer actually adds", async () => {
+        const { defaultArgs } = await import("puppeteer");
+        const puppeteerHeadlessArgs = defaultArgs({ headless: true });
+        expect(puppeteerHeadlessArgs).to.include.members([
+            ...HEADLESS_DEFAULT_ARGS_TO_DROP,
+            "--enable-automation",
+        ]);
+    });
+    it("keeps only --enable-automation ignored in headed mode", () => {
+        expect(newContext(false).getPuppeteerLaunchOptions().ignoreDefaultArgs).to.deep.equal(["--enable-automation"]);
+    });
+    it("does not leak args between instances", () => {
+        const first = launchArgs(true).length;
+        launchArgs(true);
+        expect(launchArgs(true).length).to.equal(first);
+    });
+});

package/dist/services/onboarding/onboarding-service-factory.js

@@ -83,9 +83,10 @@ export class OnboardingServiceFactory {
         const fileWatcher = new FileWatcher(cli, customerConfig, files, documentHandler, browserContext, cache);
         const athenaClient = (await this.getAthenaClient(customerConfig.app)) || null;
         const messageHandler = await this.prepareMessagehandler(athenaClient, files, customerConfig);
-        const fetchHandler = await this.getFetchEventHandler(files, customerConfig, documentHandler, cache, cli, browserContext, athenaClient, messageHandler, fileWatcher);
+        const speedKitServiceWorkerJs = new SpeedKitServiceWorkerJs(customerConfig, files.getByName(INTEGRATION_FILES.CUSTOM.SW));
+        const fetchHandler = await this.getFetchEventHandler(files, customerConfig, documentHandler, cache, cli, browserContext, athenaClient, messageHandler, fileWatcher, speedKitServiceWorkerJs);
         const extensionBridge = new ExtensionBridge(cli);
-        return new OnboardingService(browserContext, customerConfig, fetchHandler, fileWatcher, cli, messageHandler, extensionBridge);
+        return new OnboardingService(browserContext, customerConfig, fetchHandler, fileWatcher, cli, messageHandler, extensionBridge, speedKitServiceWorkerJs);
     }
     async prepareMessagehandler(athenaClient, files, customerConfig) {
         const messageHandler = new DevtoolsExtensionApi();
@@ -145,7 +146,7 @@ export class OnboardingServiceFactory {
         const configApiContext = new ConfigApiContext(app);
         return new ConfigApiServiceFactory(configApiContext).getService();
     }
-    async getFetchEventHandler(files, customerConfig, documentHandler, cache, cli, browserContext, athenaClient, messageHandler, fileWatcher) {
+    async getFetchEventHandler(files, customerConfig, documentHandler, cache, cli, browserContext, athenaClient, messageHandler, fileWatcher, speedKitServiceWorkerJs) {
         const configApi = this.getConfigApi(customerConfig.app);
         const serverConfig = await this.getSpeedKitServerConfig(configApi, cli);
         const agent = this.getCrawlerAgent(customerConfig, cli);
@@ -162,7 +163,7 @@ export class OnboardingServiceFactory {
             new SpeedKitInstallHtml(customerConfig, browserContext, new InstallSpeedKitHtmlTemplate()),
             new SpeedKitInstallJs(customerConfig, files.getByName(INTEGRATION_FILES.BUILD.INSTALL)),
             new CustomerServiceWorkerJs(customerConfig),
-            new SpeedKitServiceWorkerJs(customerConfig, files.getByName(INTEGRATION_FILES.CUSTOM.SW)),
+            speedKitServiceWorkerJs,
             new DashboardRequest(new Dashboard(customerConfig, parameterQueryBuilder, athenaClient, requestDiffService, new DiffAgainstCurrentPage(DiffService, documentHandler, crawler, cli), cache)),
         ];
         if (this.context.local) {

package/dist/services/onboarding/onboarding-service.d.ts

@@ -1,6 +1,7 @@
 import { CustomerConfig } from "../integration-api/index.js";
 import { BrowserContext } from "./onboarding-model.js";
 import { FetchEventHandler } from "./fetch-event-handler.js";
+import { SpeedKitServiceWorkerJs } from "./fetch-events/speed-kit-service-worker-js.js";
 import { FileWatcher } from "./file-events/file-watcher.js";
 import { CliService } from "../cli/index.js";
 import { DevtoolsExtensionApi } from "./browser/extension/devtools-extension-api.js";
@@ -16,8 +17,11 @@ export declare class OnboardingService {
     private cli;
     private developmentToolsMessages;
     private extensionBridge;
+    private speedKitServiceWorkerJs;
     private reinstallOnNextNavigate;
-    constructor(browserContext: BrowserContext, customerConfig: CustomerConfig, fetchEventHandler: FetchEventHandler, fileWatcher: FileWatcher, cli: CliService, developmentToolsMessages: DevtoolsExtensionApi, extensionBridge: ExtensionBridge);
+    private lastForeignSwReinstall;
+    private readonly activatedSwVersions;
+    constructor(browserContext: BrowserContext, customerConfig: CustomerConfig, fetchEventHandler: FetchEventHandler, fileWatcher: FileWatcher, cli: CliService, developmentToolsMessages: DevtoolsExtensionApi, extensionBridge: ExtensionBridge, speedKitServiceWorkerJs: SpeedKitServiceWorkerJs);
     /**
      * Prepare the puppeteer browser, wire event listeners, navigate to the
      * install page, then block until either the caller aborts the signal
@@ -37,6 +41,26 @@ export declare class OnboardingService {
     private attachExtensionBridge;
     private findPage;
     private prepareCleanState;
+    /**
+     * Detects when the DEPLOYED service worker takes over the local session and
+     * repairs it by reinstalling through the install page.
+     *
+     * Chrome's SW update checker fetches the wrapper and its imported sw.js in
+     * the browser process, where CDP Fetch interception does not apply — those
+     * fetches reach production. Because the production wrapper differs from the
+     * locally served one, any update check that slips through installs the
+     * deployed build. With static routing (`activateStaticRouting`), that is no
+     * longer harmless: routes are frozen at install time from the deployed
+     * config, so pages only enabled locally bypass the SW entirely (symptom:
+     * `responseCause: "SwBooting"` on every navigation of those pages).
+     *
+     * Only page-initiated `register()` script fetches are interceptable, so a
+     * version that activates without `SpeedKitServiceWorkerJs` having served
+     * sw.js just before must be a takeover — reinstall via the install page,
+     * which goes through the intercepted path again.
+     */
+    private registerForeignSwGuard;
+    private isForeignSwVersion;
     private reinstallSpeedKit;
     private registerFileWatcher;
     private registerReinstallSpeedKitOnNavigate;

package/dist/services/onboarding/onboarding-service.js

@@ -1,6 +1,11 @@
 import puppeteerExtra from "puppeteer-extra";
 import { BROWSER_EVENTS, CDP_SESSION, } from "./onboarding-model.js";
 import { safe } from "../../helpers/safe.js";
+// A SW version activating later than this after the last locally served sw.js
+// cannot originate from our interception — it is a deployed-build takeover.
+const LOCAL_SW_SERVE_GRACE_MS = 10_000;
+// Takeovers can retrigger on every update check — don't reinstall in a tight loop.
+const FOREIGN_SW_REINSTALL_COOLDOWN_MS = 30_000;
 /**
  * Represents the OnboardingService which is responsible for setting up the browser to test a config using Puppeteer.
  */
@@ -12,8 +17,11 @@ export class OnboardingService {
     cli;
     developmentToolsMessages;
     extensionBridge;
+    speedKitServiceWorkerJs;
     reinstallOnNextNavigate = false;
-    constructor(browserContext, customerConfig, fetchEventHandler, fileWatcher, cli, developmentToolsMessages, extensionBridge) {
+    lastForeignSwReinstall = 0;
+    activatedSwVersions = new Set();
+    constructor(browserContext, customerConfig, fetchEventHandler, fileWatcher, cli, developmentToolsMessages, extensionBridge, speedKitServiceWorkerJs) {
         this.browserContext = browserContext;
         this.customerConfig = customerConfig;
         this.fetchEventHandler = fetchEventHandler;
@@ -21,6 +29,7 @@ export class OnboardingService {
         this.cli = cli;
         this.developmentToolsMessages = developmentToolsMessages;
         this.extensionBridge = extensionBridge;
+        this.speedKitServiceWorkerJs = speedKitServiceWorkerJs;
     }
     /**
      * Prepare the puppeteer browser, wire event listeners, navigate to the
@@ -102,6 +111,7 @@ export class OnboardingService {
         });
         await cdpSession.send("Emulation.clearDeviceMetricsOverride");
         await cdpSession.send("Emulation.clearGeolocationOverride");
+        this.registerForeignSwGuard(page, cdpSession);
         safe(() => {
             cdpSession.on(CDP_SESSION.EVENTS.SERVICE_WORKER.REGISTRATION_UPDATED, ({ registrations, }) => {
                 for (const registration of registrations) {
@@ -116,6 +126,65 @@ export class OnboardingService {
             });
         });
     }
+    /**
+     * Detects when the DEPLOYED service worker takes over the local session and
+     * repairs it by reinstalling through the install page.
+     *
+     * Chrome's SW update checker fetches the wrapper and its imported sw.js in
+     * the browser process, where CDP Fetch interception does not apply — those
+     * fetches reach production. Because the production wrapper differs from the
+     * locally served one, any update check that slips through installs the
+     * deployed build. With static routing (`activateStaticRouting`), that is no
+     * longer harmless: routes are frozen at install time from the deployed
+     * config, so pages only enabled locally bypass the SW entirely (symptom:
+     * `responseCause: "SwBooting"` on every navigation of those pages).
+     *
+     * Only page-initiated `register()` script fetches are interceptable, so a
+     * version that activates without `SpeedKitServiceWorkerJs` having served
+     * sw.js just before must be a takeover — reinstall via the install page,
+     * which goes through the intercepted path again.
+     */
+    registerForeignSwGuard(page, cdpSession) {
+        cdpSession.on(CDP_SESSION.EVENTS.SERVICE_WORKER.VERSION_UPDATED, async ({ versions, }) => {
+            for (const version of versions) {
+                if (!this.isForeignSwVersion(version)) {
+                    continue;
+                }
+                this.cli.writeWarning(`${this.cli.style.yellow("Deployed Service Worker took over")} (version ${version.versionId}) — an update check bypassed the local interception. Reinstalling the local build.`);
+                this.developmentToolsMessages.addMessage({
+                    id: "serviceWorker",
+                    data: `Deployed Service Worker took over (version ${version.versionId}); reinstalling the local build`,
+                });
+                if (Date.now() - this.lastForeignSwReinstall <
+                    FOREIGN_SW_REINSTALL_COOLDOWN_MS) {
+                    continue;
+                }
+                this.lastForeignSwReinstall = Date.now();
+                await safe(this.reinstallSpeedKit(page, new URL(page.url()).pathname));
+            }
+        });
+    }
+    isForeignSwVersion(version) {
+        if (version.status !== "activated") {
+            return false;
+        }
+        // Only guard the Speed Kit wrapper; ignore the empty SWs on disabledScopes
+        // and any site-own service workers.
+        if (!version.scriptURL.includes(this.customerConfig.swPath)) {
+            return false;
+        }
+        if (version.scriptURL.includes("empty=1")) {
+            return false;
+        }
+        // Activation events repeat per version (runningStatus changes) — handle each version once.
+        if (this.activatedSwVersions.has(version.versionId)) {
+            return false;
+        }
+        this.activatedSwVersions.add(version.versionId);
+        // A locally served sw.js right before the activation means we installed it.
+        return (Date.now() - this.speedKitServiceWorkerJs.lastServedAt >
+            LOCAL_SW_SERVE_GRACE_MS);
+    }
     async reinstallSpeedKit(page, pathname) {
         const url = new URL(page.url());
         let target = url.href;

package/oclif.manifest.json

@@ -1001,5 +1001,5 @@
       ]
     }
   },
-  "version": "4.20.2"
+  "version": "4.20.4"
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@speedkit/cli",
   "description": "Speed Kit CLI",
-  "version": "4.20.2",
+  "version": "4.20.4",
   "author": {
     "name": "Baqend.com",
     "email": "info@baqend.com"