sliccy 6.154.1 → 6.154.3

package/dist/node-server/browser-shutdown.d.ts

@@ -1,7 +1,12 @@
 import type { ChildProcess } from 'node:child_process';
+import WebSocket from 'ws';
 export interface LaunchedBrowserHandle {
     launchedBrowserProcess: ChildProcess | null;
     launchedBrowserLabel: string;
 }
+export interface BrowserShutdownDependencies {
+    fetchImpl?: typeof fetch;
+    createWebSocket?: (url: string) => WebSocket;
+}
 /** Best-effort graceful close of the launched browser, escalating to SIGKILL. */
-export declare function closeLaunchedBrowserGracefully(state: LaunchedBrowserHandle, cdpPort: number): Promise<void>;
+export declare function closeLaunchedBrowserGracefully(state: LaunchedBrowserHandle, cdpPort: number, dependencies?: BrowserShutdownDependencies): Promise<void>;

package/dist/node-server/browser-shutdown.js

@@ -1,16 +1,16 @@
 import WebSocket from 'ws';
 import { probeCdpAlive } from './chrome-launch.js';
 /** Best-effort graceful close of the launched browser, escalating to SIGKILL. */
-export async function closeLaunchedBrowserGracefully(state, cdpPort) {
+export async function closeLaunchedBrowserGracefully(state, cdpPort, dependencies = {}) {
     const browser = state.launchedBrowserProcess;
     if (!browser)
         return;
     try {
-        const res = await fetch(`http://127.0.0.1:${cdpPort}/json/version`, {
+        const res = await (dependencies.fetchImpl ?? fetch)(`http://127.0.0.1:${cdpPort}/json/version`, {
             signal: AbortSignal.timeout(500),
         });
         const json = (await res.json());
-        const browserWs = new WebSocket(json.webSocketDebuggerUrl);
+        const browserWs = (dependencies.createWebSocket ?? ((url) => new WebSocket(url)))(json.webSocketDebuggerUrl);
         await new Promise((resolve, reject) => {
             browserWs.on('open', () => {
                 try {

package/dist/node-server/chrome-launch.d.ts

@@ -1,5 +1,6 @@
 import type { ChildProcess } from 'child_process';
 import { existsSync, readdirSync } from 'fs';
+import { request as httpRequest } from 'http';
 /**
  * Default startup timeout for Chrome's CDP listener. Overridable via the
  * `SLICC_CDP_LAUNCH_TIMEOUT_MS` environment variable so cold/contended CI
@@ -235,6 +236,8 @@ export interface ProbeCdpAliveOptions {
      * for ours.
      */
     expectedWebSocketPath?: string | null;
+    /** Test seam for synchronous request-construction failures. */
+    requestImpl?: typeof httpRequest;
 }
 /**
  * Single-shot HTTP probe of Chrome's `/json/version` endpoint. Resolves

package/dist/node-server/chrome-launch.js

@@ -800,6 +800,7 @@ function defaultPidIsAlive(pid) {
 export function probeCdpAlive(port, options = {}) {
     const timeoutMs = options.timeoutMs ?? 500;
     const expectedWebSocketPath = options.expectedWebSocketPath ?? null;
+    const requestImpl = options.requestImpl ?? httpRequest;
     return new Promise((resolve) => {
         let resolved = false;
         const settle = (alive) => {
@@ -819,7 +820,7 @@ export function probeCdpAlive(port, options = {}) {
         }
         let req;
         try {
-            req = httpRequest({
+            req = requestImpl({
                 host: '127.0.0.1',
                 port,
                 path: '/json/version',

package/dist/node-server/electron-controller.d.ts

@@ -1,5 +1,7 @@
-import { BRIDGE_ROLE_FOLLOWER, BRIDGE_ROLE_LEADER, BRIDGE_ROLE_QUERY_PARAM } from './_shared/index.js';
-import { type ChildProcess } from 'child_process';
+import { BRIDGE_ROLE_FOLLOWER, BRIDGE_ROLE_LEADER, BRIDGE_ROLE_QUERY_PARAM, type CDPPayload } from './_shared/index.js';
+import { type ChildProcess, type SpawnOptions } from 'child_process';
+import * as http from 'http';
+import { WebSocket } from 'ws';
 import { type ElectronInspectableTarget } from './electron-runtime.js';
 export { BRIDGE_ROLE_FOLLOWER, BRIDGE_ROLE_LEADER, BRIDGE_ROLE_QUERY_PARAM };
 /**
@@ -72,6 +74,8 @@ interface RunningProcessInfo {
     commandLine: string;
     executablePath: string | null;
 }
+/** Send a CDP command over a target WebSocket; returns the message id. */
+export type CdpSend = (method: string, params?: CDPPayload) => number;
 /**
  * One element of a CDP `Network.Request.postDataEntries` array. `bytes` is the
  * protocol `binary` type — base64 in the JSON wire form, so it survives bodies
@@ -86,11 +90,31 @@ export declare function findMatchingElectronAppPids(runningProcesses: RunningPro
 export declare class ElectronAppAlreadyRunningError extends Error {
     constructor(message: string);
 }
+export declare function parseUnixProcessList(stdout: string): RunningProcessInfo[];
+export declare function parseWindowsProcessList(stdout: string): RunningProcessInfo[];
+export declare function listRunningProcesses(platform?: NodeJS.Platform, run?: (command: string, args: string[]) => Promise<{
+    stdout: string;
+}>): Promise<RunningProcessInfo[]>;
+export declare function isPidAlive(pid: number, signal?: (pid: number, signal: 0) => void): boolean;
+interface ProcessLifecycle {
+    isAlive: (pid: number) => boolean;
+    kill: (pid: number, signal?: NodeJS.Signals) => void;
+    now: () => number;
+    sleep: (milliseconds: number) => Promise<void>;
+}
+export declare function waitForPidsToExit(pids: number[], timeoutMs?: number, lifecycle?: ProcessLifecycle): Promise<boolean>;
+export declare function terminateRunningApp(pids: number[], lifecycle?: ProcessLifecycle): Promise<void>;
+export declare function findRunningElectronAppPids(appPath: string, platform?: NodeJS.Platform): Promise<number[]>;
 export declare function launchElectronApp(options: {
     appPath: string;
     cdpPort: number;
     kill: boolean;
     platform?: NodeJS.Platform;
+}, dependencies?: {
+    exists?: (path: string) => boolean;
+    findRunningPids?: (appPath: string, platform?: NodeJS.Platform) => Promise<number[]>;
+    terminate?: (pids: number[]) => Promise<void>;
+    spawn?: (command: string, args: string[], options: SpawnOptions) => ChildProcess;
 }): Promise<{
     child: ChildProcess;
     displayName: string;
@@ -109,6 +133,12 @@ export declare function decodePngPixels(base64Data: string): {
  * sampling a grid of pixels for performance.
  */
 export declare function computeAverageLuminance(pixels: Buffer, width: number, height: number, sampleStep?: number): number;
+/**
+ * Detect whether the target app is using a light or dark theme by taking
+ * a CDP screenshot and analyzing the average luminance.
+ * Returns 'light' or 'dark'.
+ */
+export declare function detectAppThemeFromScreenshot(ws: WebSocket, send: CdpSend): Promise<'light' | 'dark'>;
 /**
  * Resolve the `Fetch.enable` origin pattern for CSP-bypass escalation. Mirrors
  * swift-server's `OverlayTargetSession.fetchProxyOrigin` (Wave 5): prefer the
@@ -159,6 +189,20 @@ export declare function decodeCdpRequestPostBody(request: {
     hasPostData?: boolean;
     postDataEntries?: CdpPostDataEntry[];
 }): CdpPostBody;
+/**
+ * Translate a Node http(s) response's headers into the array shape required by
+ * `Fetch.fulfillRequest`, stripping CSP and other hop-by-hop headers that are
+ * invalid in fulfill responses and rewriting `content-length` to match the
+ * actually-buffered body length. Returns whether any CSP header was stripped
+ * so the caller can log it.
+ */
+export declare function buildFulfillResponseHeaders(rawHeaders: http.IncomingHttpHeaders, contentLength: number): {
+    responseHeaders: Array<{
+        name: string;
+        value: string;
+    }>;
+    strippedCSP: boolean;
+};
 /**
  * Pre-built bootstrap scripts for thin-mode injection — one per overlay
  * role. The injector picks `leader` for the first injected target and
@@ -175,6 +219,9 @@ export interface ThinBootstrapSet {
      */
     status: string;
 }
+export declare function logOverlayReinjectionFailure(context: string, error: unknown): void;
+export declare const logPresenceReinjectionFailure: (error: unknown) => void;
+export declare const logNavigationReinjectionFailure: (error: unknown) => void;
 /**
  * Empty-viewport message shown by the status-only overlay for an app that
  * denies the overlay iframe's network egress. Kept in sync with swift-server's
@@ -265,6 +312,7 @@ export declare class ElectronOverlayInjector {
     private readonly onEgressBlocked?;
     private syncTimer;
     private syncing;
+    private readonly runScheduledSync;
     private constructor();
     static create(options: {
         cdpPort: number;
@@ -318,6 +366,18 @@ export declare class ElectronOverlayInjector {
     _testingEgressBlockedTargets(): ReadonlySet<string>;
     /** Test-only: seed a target as already egress-blocked. */
     _testingSeedEgressBlockedTarget(url: string): void;
+    /** Test-only: seed a connection so sync/stop cleanup can be driven deterministically. */
+    _testingSeedConnection(targetId: string, connection: Pick<WebSocket, 'close'>): void;
+    /** Test-only: drive the identity-guarded connection cleanup. */
+    _testingDropConnection(targetId: string, connection: WebSocket): void;
+    /** Test-only: invoke the same callback installed by `start()`. */
+    _testingRunScheduledSync(): Promise<void>;
+    /** Test-only: exercise the overlay-loaded timeout classifier directly. */
+    _testingProbeOverlayIframeLoaded(ws: WebSocket, send: CdpSend): Promise<boolean>;
+    /** Test-only: exercise the overlay-eviction timeout classifier directly. */
+    _testingProbeOverlayEvicted(ws: WebSocket, send: CdpSend): Promise<boolean>;
+    /** Test-only: drive a paused Fetch event without requiring the full escalation flow. */
+    _testingHandleFetchRequestPaused(ws: WebSocket, send: CdpSend, msg: unknown): void;
     /** Test-only: drive a single `syncTargets` pass without `start()`'s interval. */
     _testingSyncTargets(): Promise<void>;
     /** Test-only: close any sockets opened by `_testingConnectToTarget`. */
@@ -325,6 +385,7 @@ export declare class ElectronOverlayInjector {
     start(): Promise<void>;
     stop(): void;
     private syncTargets;
+    private dropConnectionIfCurrent;
     /**
      * Check if the overlay iframe loaded successfully by evaluating a probe
      * script. Walks the `<slicc-launcher>` host's (open) shadow root to find the

package/dist/node-server/electron-controller.js

@@ -1,5 +1,5 @@
 import { BRIDGE_ROLE_FOLLOWER, BRIDGE_ROLE_LEADER, BRIDGE_ROLE_QUERY_PARAM, ELECTRON_OVERLAY_APP_PATH, SLICC_HOSTED_ORIGIN, TRAY_QUERY_PARAM, } from './_shared/index.js';
-import { execFile as nodeExecFile, spawn } from 'child_process';
+import { execFile as nodeExecFile, spawn, } from 'child_process';
 import { existsSync } from 'fs';
 import { readFile } from 'fs/promises';
 import * as http from 'http';
@@ -105,7 +105,7 @@ export class ElectronAppAlreadyRunningError extends Error {
         this.name = 'ElectronAppAlreadyRunningError';
     }
 }
-function parseUnixProcessList(stdout) {
+export function parseUnixProcessList(stdout) {
     const processes = [];
     for (const rawLine of stdout.split('\n')) {
         const line = rawLine.trim();
@@ -125,7 +125,7 @@ function parseUnixProcessList(stdout) {
     }
     return processes;
 }
-function parseWindowsProcessList(stdout) {
+export function parseWindowsProcessList(stdout) {
     const trimmed = stdout.trim();
     if (!trimmed)
         return [];
@@ -139,93 +139,101 @@ function parseWindowsProcessList(stdout) {
     }))
         .filter((processInfo) => Number.isFinite(processInfo.pid) && processInfo.pid > 0);
 }
-async function listRunningProcesses(platform = process.platform) {
+export async function listRunningProcesses(platform = process.platform, run = execFile) {
     if (platform === 'win32') {
-        const { stdout } = await execFile('powershell', [
+        const { stdout } = await run('powershell', [
             '-NoProfile',
             '-Command',
             'Get-CimInstance Win32_Process | Select-Object ProcessId, ExecutablePath, CommandLine | ConvertTo-Json -Compress',
         ]);
         return parseWindowsProcessList(stdout);
     }
-    const { stdout } = await execFile('ps', ['-ax', '-o', 'pid=', '-o', 'command=']);
+    const { stdout } = await run('ps', ['-ax', '-o', 'pid=', '-o', 'command=']);
     return parseUnixProcessList(stdout);
 }
-function isPidAlive(pid) {
+export function isPidAlive(pid, signal = process.kill.bind(process)) {
     try {
-        process.kill(pid, 0);
+        signal(pid, 0);
         return true;
     }
     catch {
         return false;
     }
 }
-async function waitForPidsToExit(pids, timeoutMs = 5000) {
-    const deadline = Date.now() + timeoutMs;
-    while (Date.now() < deadline) {
-        if (pids.every((pid) => !isPidAlive(pid)))
+const defaultProcessLifecycle = {
+    isAlive: isPidAlive,
+    kill: (pid, signal) => process.kill(pid, signal),
+    now: Date.now,
+    sleep: (milliseconds) => new Promise((resolve) => setTimeout(resolve, milliseconds)),
+};
+export async function waitForPidsToExit(pids, timeoutMs = 5000, lifecycle = defaultProcessLifecycle) {
+    const deadline = lifecycle.now() + timeoutMs;
+    while (lifecycle.now() < deadline) {
+        if (pids.every((pid) => !lifecycle.isAlive(pid)))
             return true;
-        await new Promise((resolve) => setTimeout(resolve, 100));
+        await lifecycle.sleep(100);
     }
-    return pids.every((pid) => !isPidAlive(pid));
+    return pids.every((pid) => !lifecycle.isAlive(pid));
 }
-async function terminateRunningApp(pids) {
+export async function terminateRunningApp(pids, lifecycle = defaultProcessLifecycle) {
     for (const pid of pids) {
-        if (!isPidAlive(pid))
+        if (!lifecycle.isAlive(pid))
             continue;
         try {
-            process.kill(pid);
+            lifecycle.kill(pid);
         }
         catch {
             // Ignore individual termination failures and fall back to force-kill below if needed.
         }
     }
-    if (await waitForPidsToExit(pids))
+    if (await waitForPidsToExit(pids, 5000, lifecycle))
         return;
     for (const pid of pids) {
-        if (!isPidAlive(pid))
+        if (!lifecycle.isAlive(pid))
             continue;
         try {
-            process.kill(pid, 'SIGKILL');
+            lifecycle.kill(pid, 'SIGKILL');
         }
         catch {
             // Ignore final cleanup failures.
         }
     }
-    await waitForPidsToExit(pids, 3000);
+    await waitForPidsToExit(pids, 3000, lifecycle);
 }
-async function findRunningElectronAppPids(appPath, platform = process.platform) {
+export async function findRunningElectronAppPids(appPath, platform = process.platform) {
     const { processMatchPatterns } = buildElectronAppLaunchSpec(appPath, { cdpPort: 0, platform });
     const runningProcesses = await listRunningProcesses(platform);
     return findMatchingElectronAppPids(runningProcesses, processMatchPatterns);
 }
-export async function launchElectronApp(options) {
+export async function launchElectronApp(options, dependencies = {}) {
     const launchSpec = buildElectronAppLaunchSpec(options.appPath, {
         cdpPort: options.cdpPort,
         platform: options.platform,
     });
-    if (!existsSync(launchSpec.resolvedAppPath)) {
+    const exists = dependencies.exists ?? existsSync;
+    if (!exists(launchSpec.resolvedAppPath)) {
         throw new Error(`Electron app not found at ${launchSpec.resolvedAppPath}`);
     }
-    if (!existsSync(launchSpec.command)) {
+    if (!exists(launchSpec.command)) {
         throw new Error(`Electron executable not found at ${launchSpec.command}. Pass the app executable path directly if needed.`);
     }
-    const runningPids = await findRunningElectronAppPids(launchSpec.resolvedAppPath, options.platform);
+    const runningPids = await (dependencies.findRunningPids ?? findRunningElectronAppPids)(launchSpec.resolvedAppPath, options.platform);
     const platform = options.platform ?? process.platform;
     const isMacAppBundle = platform === 'darwin' && launchSpec.resolvedAppPath.toLowerCase().endsWith('.app');
     if (runningPids.length > 0 && !options.kill) {
         throw new ElectronAppAlreadyRunningError(`${launchSpec.displayName} is already running. Re-run with --kill to relaunch it with remote debugging enabled.`);
     }
     if (runningPids.length > 0) {
-        await terminateRunningApp(runningPids);
+        await (dependencies.terminate ?? terminateRunningApp)(runningPids);
     }
+    const spawnProcess = dependencies.spawn ?? spawn;
     const child = isMacAppBundle
-        ? spawn('open', ['-n', '-a', launchSpec.resolvedAppPath, '-W', '--args', ...launchSpec.args], {
+        ? spawnProcess('open', ['-n', '-a', launchSpec.resolvedAppPath, '-W', '--args', ...launchSpec.args], {
             env: process.env,
             stdio: ['ignore', 'pipe', 'pipe'],
             detached: false,
         })
-        : spawn(launchSpec.command, launchSpec.args, {
+        : spawnProcess(launchSpec.command, launchSpec.args, {
             env: process.env,
             stdio: ['ignore', 'pipe', 'pipe'],
             detached: false,
@@ -369,7 +377,7 @@ export function computeAverageLuminance(pixels, width, height, sampleStep = 4) {
  * a CDP screenshot and analyzing the average luminance.
  * Returns 'light' or 'dark'.
  */
-function detectAppThemeFromScreenshot(ws, send) {
+export function detectAppThemeFromScreenshot(ws, send) {
     return new Promise((resolve) => {
         // Take a small JPEG screenshot for speed — we only need luminance
         const screenshotId = send('Page.captureScreenshot', {
@@ -524,7 +532,7 @@ function buildProxyRequestHeaders(requestHeaders, bodyLength) {
  * actually-buffered body length. Returns whether any CSP header was stripped
  * so the caller can log it.
  */
-function buildFulfillResponseHeaders(rawHeaders, contentLength) {
+export function buildFulfillResponseHeaders(rawHeaders, contentLength) {
     const HOP_BY_HOP = new Set([
         'content-security-policy',
         'content-security-policy-report-only',
@@ -558,6 +566,16 @@ function buildFulfillResponseHeaders(rawHeaders, contentLength) {
     }
     return { responseHeaders, strippedCSP };
 }
+export function logOverlayReinjectionFailure(context, error) {
+    const message = error instanceof Error ? error.message : String(error);
+    console.warn(`[electron-float] ${context} re-injection failed: ${message}`);
+}
+export const logPresenceReinjectionFailure = (error) => {
+    logOverlayReinjectionFailure('Presence-check', error);
+};
+export const logNavigationReinjectionFailure = (error) => {
+    logOverlayReinjectionFailure('Navigation', error);
+};
 /**
  * Empty-viewport message shown by the status-only overlay for an app that
  * denies the overlay iframe's network egress. Kept in sync with swift-server's
@@ -680,6 +698,9 @@ export class ElectronOverlayInjector {
     onEgressBlocked;
     syncTimer = null;
     syncing = false;
+    runScheduledSync = async () => {
+        await this.syncTargets();
+    };
     constructor(cdpPort, servePort, thinBootstraps, bridgeToken, onEgressBlocked, probeDelayMs = 1500, presenceCheckIntervalMs = ELECTRON_OVERLAY_PRESENCE_CHECK_INTERVAL_MS) {
         this.cdpPort = cdpPort;
         this.servePort = servePort;
@@ -761,6 +782,30 @@ export class ElectronOverlayInjector {
     _testingSeedEgressBlockedTarget(url) {
         this.egressBlockedTargets.add(url);
     }
+    /** Test-only: seed a connection so sync/stop cleanup can be driven deterministically. */
+    _testingSeedConnection(targetId, connection) {
+        this.connections.set(targetId, connection);
+    }
+    /** Test-only: drive the identity-guarded connection cleanup. */
+    _testingDropConnection(targetId, connection) {
+        this.dropConnectionIfCurrent(targetId, connection);
+    }
+    /** Test-only: invoke the same callback installed by `start()`. */
+    async _testingRunScheduledSync() {
+        await this.runScheduledSync();
+    }
+    /** Test-only: exercise the overlay-loaded timeout classifier directly. */
+    _testingProbeOverlayIframeLoaded(ws, send) {
+        return this.probeOverlayIframeLoaded(ws, send);
+    }
+    /** Test-only: exercise the overlay-eviction timeout classifier directly. */
+    _testingProbeOverlayEvicted(ws, send) {
+        return this.probeOverlayEvicted(ws, send);
+    }
+    /** Test-only: drive a paused Fetch event without requiring the full escalation flow. */
+    _testingHandleFetchRequestPaused(ws, send, msg) {
+        this.handleFetchRequestPaused(ws, send, msg);
+    }
     /** Test-only: drive a single `syncTargets` pass without `start()`'s interval. */
     async _testingSyncTargets() {
         await this.syncTargets();
@@ -779,9 +824,7 @@ export class ElectronOverlayInjector {
     }
     async start() {
         await this.syncTargets();
-        this.syncTimer = setInterval(() => {
-            void this.syncTargets();
-        }, ELECTRON_OVERLAY_SYNC_INTERVAL_MS);
+        this.syncTimer = setInterval(this.runScheduledSync, ELECTRON_OVERLAY_SYNC_INTERVAL_MS);
     }
     stop() {
         if (this.syncTimer) {
@@ -853,6 +896,11 @@ export class ElectronOverlayInjector {
             this.syncing = false;
         }
     }
+    dropConnectionIfCurrent(targetId, connection) {
+        if (this.connections.get(targetId) === connection) {
+            this.connections.delete(targetId);
+        }
+    }
     /**
      * Check if the overlay iframe loaded successfully by evaluating a probe
      * script. Walks the `<slicc-launcher>` host's (open) shadow root to find the
@@ -1310,10 +1358,7 @@ export class ElectronOverlayInjector {
         ws.on('open', () => {
             this.handleSocketOpen(ws, send, target, state);
             presenceTimer = setInterval(() => {
-                void this.reinjectIfEvicted(ws, send, target, state).catch((error) => {
-                    const message = error instanceof Error ? error.message : String(error);
-                    console.warn(`[electron-float] Presence-check re-injection failed: ${message}`);
-                });
+                void this.reinjectIfEvicted(ws, send, target, state).catch(logPresenceReinjectionFailure);
             }, this.presenceCheckIntervalMs);
         });
         // Handle CDP events: lifecycle events and Fetch interception
@@ -1332,10 +1377,7 @@ export class ElectronOverlayInjector {
                 // navigation a no-op (its marker is wiped, so the new-document hook owns it).
                 const isMainFrameNavigated = msg.method === 'Page.frameNavigated' && !msg.params?.frame?.parentId;
                 if (msg.method === 'Page.navigatedWithinDocument' || isMainFrameNavigated) {
-                    void this.reinjectIfEvicted(ws, send, target, state).catch((error) => {
-                        const message = error instanceof Error ? error.message : String(error);
-                        console.warn(`[electron-float] Navigation re-injection failed: ${message}`);
-                    });
+                    void this.reinjectIfEvicted(ws, send, target, state).catch(logNavigationReinjectionFailure);
                 }
                 if (msg.method === 'Fetch.requestPaused' && state.fetchProxyActive) {
                     this.handleFetchRequestPaused(ws, send, msg);
@@ -1352,17 +1394,13 @@ export class ElectronOverlayInjector {
         });
         ws.on('close', () => {
             clearPresenceTimer();
-            if (this.connections.get(targetId) === ws) {
-                this.connections.delete(targetId);
-            }
+            this.dropConnectionIfCurrent(targetId, ws);
         });
         ws.on('error', (error) => {
             clearPresenceTimer();
             const message = error instanceof Error ? error.message : String(error);
             console.error(`[electron-float] Overlay target connection failed for ${target.url}:`, message);
-            if (this.connections.get(targetId) === ws) {
-                this.connections.delete(targetId);
-            }
+            this.dropConnectionIfCurrent(targetId, ws);
         });
     }
 }

package/dist/node-server/electron-runtime.d.ts

@@ -32,12 +32,25 @@ export declare const PORT_HASH_RANGE = 40;
  * Exported for testing.
  */
 export declare function hashString(str: string, max: number): number;
+/**
+ * Try to listen on a specific port and host, returning the assigned port.
+ */
+export declare function tryListenOnPort(port: number, host: string): Promise<number>;
+/**
+ * Check if a port is available on both IPv4 (127.0.0.1) and IPv6 (::1).
+ * On macOS, `localhost` resolves to `::1`, so we need to check both.
+ */
+export declare function isPortAvailable(port: number, listen?: (port: number, host: string) => Promise<number>): Promise<boolean>;
+/**
+ * Find an available port starting from the given port.
+ */
+export declare function findAvailablePort(startPort: number, maxAttempts?: number, available?: (port: number) => Promise<boolean>): Promise<number>;
 /**
  * Get a port for an Electron app based on its path.
  * Uses hash-based offset from base port, with fallback to next available port
  * starting from the preferred port (to stay in the app's "slot" range).
  */
-export declare function getElectronAppPort(appPath: string, basePort: number): Promise<number>;
+export declare function getElectronAppPort(appPath: string, basePort: number, available?: (port: number) => Promise<boolean>): Promise<number>;
 /**
  * Get both CDP and serve ports for an Electron app.
  */
@@ -46,6 +59,7 @@ export declare function getElectronAppPorts(appPath: string): Promise<{
     servePort: number;
 }>;
 export declare function getElectronAppDisplayName(appPath: string): string;
+export declare function isExecutableFile(path: string): boolean;
 export declare function resolveElectronAppExecutablePath(appPath: string, platform?: NodeJS.Platform): string;
 export declare function buildElectronAppProcessMatchPatterns(appPath: string, platform?: NodeJS.Platform): string[];
 export declare function buildElectronAppLaunchSpec(appPath: string, options: {

package/dist/node-server/electron-runtime.js

@@ -22,7 +22,7 @@ export function hashString(str, max) {
 /**
  * Try to listen on a specific port and host, returning the assigned port.
  */
-async function tryListenOnPort(port, host) {
+export async function tryListenOnPort(port, host) {
     const { createServer } = await import('net');
     return new Promise((resolve, reject) => {
         const server = createServer();
@@ -38,11 +38,11 @@ async function tryListenOnPort(port, host) {
  * Check if a port is available on both IPv4 (127.0.0.1) and IPv6 (::1).
  * On macOS, `localhost` resolves to `::1`, so we need to check both.
  */
-async function isPortAvailable(port) {
+export async function isPortAvailable(port, listen = tryListenOnPort) {
     try {
-        await tryListenOnPort(port, '127.0.0.1');
+        await listen(port, '127.0.0.1');
         try {
-            await tryListenOnPort(port, '::1');
+            await listen(port, '::1');
         }
         catch (err) {
             // ::1 may not be available on some systems — only fail on EADDRINUSE
@@ -59,10 +59,10 @@ async function isPortAvailable(port) {
 /**
  * Find an available port starting from the given port.
  */
-async function findAvailablePort(startPort, maxAttempts = 100) {
+export async function findAvailablePort(startPort, maxAttempts = 100, available = isPortAvailable) {
     for (let i = 0; i < maxAttempts; i++) {
         const port = startPort + i;
-        if (await isPortAvailable(port)) {
+        if (await available(port)) {
             return port;
         }
     }
@@ -73,14 +73,14 @@ async function findAvailablePort(startPort, maxAttempts = 100) {
  * Uses hash-based offset from base port, with fallback to next available port
  * starting from the preferred port (to stay in the app's "slot" range).
  */
-export async function getElectronAppPort(appPath, basePort) {
+export async function getElectronAppPort(appPath, basePort, available = isPortAvailable) {
     const offset = hashString(appPath, PORT_HASH_RANGE);
     const preferredPort = basePort + offset;
-    if (await isPortAvailable(preferredPort)) {
+    if (await available(preferredPort)) {
         return preferredPort;
     }
     // Fallback: find next available port starting from preferred (stay in slot range)
-    return findAvailablePort(preferredPort + 1);
+    return findAvailablePort(preferredPort + 1, 100, available);
 }
 /**
  * Get both CDP and serve ports for an Electron app.
@@ -98,7 +98,7 @@ export function getElectronAppDisplayName(appPath) {
     }
     return fileName || trimmedPath;
 }
-function isExecutableFile(path) {
+export function isExecutableFile(path) {
     try {
         accessSync(path, constants.X_OK);
         return true;

package/dist/node-server/fetch-proxy-gzip.js

@@ -69,13 +69,11 @@ class MaybeGunzipTransform extends Transform {
                 cb();
                 return;
             }
-            this.#finishDecide((err) => {
-                if (err) {
-                    cb(err);
-                    return;
-                }
-                this.#endGunzipOrFinish(cb);
-            });
+            // A non-empty undecided head can only be one byte: two bytes decide in
+            // `_transform`. One byte cannot be gzip magic, so flush it directly.
+            this.#decided = true;
+            this.#onDecided?.(false);
+            cb(null, this.#head);
             return;
         }
         this.#endGunzipOrFinish(cb);

package/dist/node-server/hosted-bootstrap.d.ts

@@ -2,6 +2,7 @@ import { type Account, imsTokenExpiry } from './_cloud_core/src/index.js';
 import type { Express } from 'express';
 import type { SecretStore } from './secrets/types.js';
 export { imsTokenExpiry };
+export declare function readHostedConeConfig(path?: string, read?: (path: string, encoding: BufferEncoding) => string, warn?: (...args: unknown[]) => void): string | null;
 export interface HostedBootstrapPayload {
     model?: string;
     effortLevel?: string;

package/dist/node-server/hosted-bootstrap.js

@@ -24,6 +24,17 @@ import { requireLoopback } from './cloud-status.js';
 // Buffer-free) so the worker's back-compat + resume paths reuse the same logic.
 export { imsTokenExpiry };
 const CONE_CONFIG_PATH = '/slicc/cone-config.json';
+export function readHostedConeConfig(path = CONE_CONFIG_PATH, read = readFileSync, warn = console.warn) {
+    try {
+        return read(path, 'utf-8');
+    }
+    catch (err) {
+        if (err.code !== 'ENOENT') {
+            warn('[hosted-bootstrap] failed to read cone-config.json:', err);
+        }
+        return null;
+    }
+}
 export function buildHostedBootstrapPayload(sources) {
     const raw = sources.readConeConfig();
     if (raw) {
@@ -55,20 +66,7 @@ export function buildHostedBootstrapPayload(sources) {
 export function registerHostedBootstrapEndpoint(app, options) {
     app.get('/api/hosted-bootstrap', requireLoopback, (_req, res) => {
         const payload = buildHostedBootstrapPayload({
-            readConeConfig: () => {
-                try {
-                    return readFileSync(CONE_CONFIG_PATH, 'utf-8');
-                }
-                catch (err) {
-                    // A missing file is the normal pre-feature/back-compat case. Any other
-                    // error (EACCES, EIO, …) means the config exists but is unreadable —
-                    // log it so a silent fallback to legacy/empty doesn't hide the cause.
-                    if (err.code !== 'ENOENT') {
-                        console.warn('[hosted-bootstrap] failed to read cone-config.json:', err);
-                    }
-                    return null;
-                }
-            },
+            readConeConfig: () => readHostedConeConfig(),
             getLegacyAdobeToken: () => options.secretStore.get('ADOBE_IMS_TOKEN')?.value,
         });
         res.json(payload);