@lincoln504/pi-research 1.1.2 → 1.3.0

package/src/core/service-interfaces.ts

@@ -9,7 +9,7 @@ export type { SearchResult, ScrapeResult, IScheduler, SchedulerMetadata, ISchedu
 export type { ISchedulerFactory } from './scheduler-factory.ts';
 
 // Health check interfaces
-export type { HealthCheckResult, HealthCheckCache, IHealthCheckService, IHealthRegistryService } from './interfaces/health-check-interfaces.ts';
+export type { IHealthRegistryService } from './interfaces/health-check-interfaces.ts';
 
 // Knowledge store interfaces
 export type { 

package/src/core/service-registry.ts

@@ -17,6 +17,13 @@ import { logger } from '../logger.ts';
 import { AsyncLocalStorage } from 'node:async_hooks';
 
 
+/**
+ * How long teardown waits for an initialization that is still in flight. Long
+ * enough to cover a normal service coming up, short enough that a service blocked
+ * on something slow (a model download) cannot hold shutdown open indefinitely.
+ */
+const DISPOSE_INFLIGHT_INIT_TIMEOUT_MS = 5_000;
+
 /**
  * Service lifecycle stages
  */
@@ -209,15 +216,52 @@ export class ServiceContainer {
       throw new Error(`Service '${name}' is not registered`);
     }
 
-    // Return existing instance if already initialized
+    // Return existing instance if already initialized.
     if (registration.instance) {
+      // `_initializeService` publishes `registration.instance` BEFORE awaiting the
+      // service's own initialize(), deliberately: a service whose initialize()
+      // resolves a peer that resolves it back would otherwise deadlock, and the
+      // partial instance is what breaks that cycle. But the same early publish
+      // hands a HALF-BUILT service to unrelated concurrent callers — e.g.
+      // StateManagerService only assigns its inner manager after nine awaited
+      // getService() calls, so every method on it throws "not initialized" until
+      // then, and the embedding factory resolves it and immediately calls
+      // updateState(). Worse, the ctx branch below would re-run initialize() on an
+      // instance that is still running it, constructing a second StateManager and
+      // discarding the first.
+      //
+      // So: if it is still initializing, wait for that to finish. The cycle case is
+      // exactly the case where `caller` is set (we are inside some service's
+      // initialize()), and there we must NOT wait — that is the deadlock the early
+      // publish exists to avoid. Outside an initialization there is no cycle to
+      // break and waiting is always correct.
+      if (registration.initializationPromise && caller === undefined) {
+        await registration.initializationPromise.catch(() => { /* surfaced below */ });
+        if (!registration.instance) {
+          // Initialization failed and cleaned up after itself — fall through and
+          // retry from scratch rather than returning a torn-down instance.
+          return this.get<T>(name, ctx);
+        }
+      }
       // Re-initialize if ctx is provided and service supports it
       if (ctx && registration.instance.initialize) {
         // Wrap in initializationContext so nested get() calls are tracked
-        return initializationContext.run(name, async () => {
+        const reinit = initializationContext.run(name, async () => {
           await registration.instance!.initialize!(ctx);
           return registration.instance as T;
         });
+        // Recorded like a first init: a re-init is just as in-flight. Without
+        // this, disposeAll's settle-wait cannot see it (it would dispose the
+        // instance under a running initialize()), and concurrent callers
+        // received the instance mid-re-initialization.
+        registration.initializationPromise = reinit as Promise<IService>;
+        const clearIfCurrent = () => {
+          if (registration.initializationPromise === (reinit as Promise<IService>)) {
+            registration.initializationPromise = null;
+          }
+        };
+        reinit.then(clearIfCurrent, clearIfCurrent);
+        return reinit;
       }
       return registration.instance as T;
     }
@@ -243,7 +287,21 @@ export class ServiceContainer {
   }
 
   /**
-   * Get a service instance synchronously (returns null if not initialized)
+   * Get a service instance synchronously (returns null if not registered or not
+   * yet constructed).
+   *
+   * Deliberately returns instances in NON-settled lifecycles too. This is a
+   * lifecycle *inspector* as much as an accessor: the health check resolves the
+   * knowledge store through it precisely so it can report `initializing` /
+   * `disabled` / `disposed (not running)` WITHOUT forcing initialization (forcing
+   * it was a past cause of 45 s CI stalls). Filtering those states out here would
+   * make every one of them indistinguishable from "absent".
+   *
+   * The trade-off: because `_initializeService` publishes the instance before
+   * awaiting its `initialize()` (to break dependency cycles), a caller that
+   * immediately *uses* the result can catch a half-built service. Callers that
+   * need a ready service must use the async `get()`, which waits — see the note
+   * there. Callers that only inspect `lifecycle` are safe by construction.
    */
   tryGet<T extends IService>(name: string): T | null {
     if (this.isDisposing) {
@@ -286,6 +344,15 @@ export class ServiceContainer {
       throw new Error(`Service '${name}' is not registered`);
     }
 
+    // Settle an in-flight initialization first. Disposing the early-published
+    // instance while its initialize() is still running hands the awaiting get()
+    // caller a service that was disposed under it — observed as store-closed
+    // errors when /research-config cleared the knowledge store during a
+    // concurrent first search.
+    if (registration.initializationPromise) {
+      await registration.initializationPromise.catch(() => { /* failed init cleaned up after itself */ });
+    }
+
     if (registration.instance && registration.instance.dispose) {
       await registration.instance.dispose().catch((err: unknown) => {
         logger.warn(`[ServiceContainer] Error disposing service '${name}':`, err);
@@ -309,6 +376,11 @@ export class ServiceContainer {
       throw new Error(`Service '${name}' is not registered`);
     }
 
+    // Settle an in-flight initialization before swapping — see clear().
+    if (registration.initializationPromise) {
+      await registration.initializationPromise.catch(() => { /* failed init cleaned up after itself */ });
+    }
+
     // Dispose old instance if present
     if (registration.instance && registration.instance.dispose) {
       await registration.instance.dispose().catch((err: unknown) => {
@@ -347,7 +419,41 @@ export class ServiceContainer {
     }
 
     try {
-      const activeServices = Array.from(this.services.keys()).filter(name => 
+      // Settle any initialization still in flight BEFORE snapshotting what to tear
+      // down. `activeServices` is "instances that are non-null right now", so a
+      // get() whose factory has not resolved yet is invisible to it — and nothing
+      // else awaits it. Such a service installs itself into the registry AFTER
+      // teardown reports completion and is never disposed: for BrowserTaskScheduler
+      // that is a listening HTTP server plus a cluster pool and Camoufox children
+      // outliving shutdown; for KnowledgeStoreService an ONNX session and LanceDB
+      // handles. (SchedulerService.dispose hand-rolls this same guard for itself,
+      // which does not help when the leaked service IS SchedulerService.)
+      //
+      // Bounded: a service blocked on something slow (a model download) must not
+      // hold teardown open indefinitely. On timeout we proceed — the snapshot below
+      // still catches anything that landed in the meantime.
+      const inFlight = Array.from(this.services.values())
+        .map((r) => r.initializationPromise)
+        .filter((p): p is Promise<IService> => p != null);
+      if (inFlight.length > 0) {
+        if (this.defaultOptions.enableLogging) {
+          logger.debug(`[ServiceContainer] Waiting for ${inFlight.length} in-flight initialization(s) before teardown`);
+        }
+        let settleTimer: ReturnType<typeof setTimeout> | undefined;
+        await Promise.race([
+          Promise.allSettled(inFlight),
+          new Promise<void>((resolve) => {
+            settleTimer = setTimeout(() => {
+              logger.warn('[ServiceContainer] Timed out waiting for in-flight service initialization; proceeding with teardown');
+              resolve();
+            }, DISPOSE_INFLIGHT_INIT_TIMEOUT_MS);
+            settleTimer.unref?.();
+          }),
+        ]);
+        if (settleTimer) clearTimeout(settleTimer);
+      }
+
+      const activeServices = Array.from(this.services.keys()).filter(name =>
         this.services.get(name)?.instance !== null
       );
       
@@ -443,14 +549,17 @@ export class ServiceContainer {
       return null;
     }
 
-    if (registration.instance) {
-      return ServiceLifecycle.INITIALIZED;
-    }
-
+    // Promise first: the instance is published BEFORE its initialize() completes
+    // (the early publish that lets dependency cycles resolve), so instance-first
+    // ordering reported a mid-initialization service as INITIALIZED.
     if (registration.initializationPromise) {
       return ServiceLifecycle.INITIALIZING;
     }
 
+    if (registration.instance) {
+      return ServiceLifecycle.INITIALIZED;
+    }
+
     return ServiceLifecycle.UNINITIALIZED;
   }
 

package/src/healthcheck/index.ts

@@ -80,7 +80,12 @@ export function registerHealthChecks(registry: IHealthRegistryService, container
     // respected (same pattern as the KnowledgeStore check's Math.max floor).
   }, { timeoutMs: Math.max(healthTimeoutMs, 150000), critical: true });
 
-  // Register Knowledge Store Check
+  // Register Knowledge Store Check — NON-critical: the store is the optional cache
+  // research must run without (see the darwin-x64 comment below). A failure here
+  // (e.g. a dead embedding server, ECONNREFUSED) must degrade health, not flip the
+  // aggregate to unhealthy: as a critical check it aborted runs, and the raw store
+  // error then fed the TUI's browser-oriented formatter, which misattributed it as
+  // "the browser hit a network error / check your internet connection".
   registry.register('KnowledgeStore', async (options) => {
     // Idle fast-path — mirrors the BrowserRuntime check above. Read the ALREADY
     // resolved instance via tryGet(), which does NOT initialize the service;
@@ -222,7 +227,7 @@ export function registerHealthChecks(registry: IHealthRegistryService, container
       }
       return { healthy: false, error: `Knowledge store healthcheck failed: ${e instanceof Error ? e.message : String(e)}` };
     }
-  }, { timeoutMs: Math.max(healthTimeoutMs, 45000) });
+  }, { timeoutMs: Math.max(healthTimeoutMs, 45000), critical: false });
 
   // Register State Manager Check
   registry.register('StateManager', async () => {

package/src/index.ts

@@ -11,6 +11,7 @@ import type { ResearchResultDetails } from './types/index.ts';
 import { createResearchTool, createHealthTool } from './tool.ts';
 import { createResearchKnowledgeSearchTool } from './tools/research-knowledge-search.ts';
 import { logger } from './logger.ts';
+import { checkPiCompatibility } from './core/pi-version.ts';
 import { randomUUID } from 'node:crypto';
 import { shutdownManager } from './utils/shutdown-manager.ts';
 import { healthRegistry } from './healthcheck/index.ts';
@@ -98,25 +99,17 @@ export default async function (pi: ExtensionAPI) {
   // 0.80.8+ host auto-building its ModelRuntime. This in-host check is the real
   // enforcement point: when running as an extension the host's version is NOT
   // constrained by npm's resolution of our own package.json range.
-  const versionParts = PI_VERSION.split('.').map(Number);
-  const major = versionParts[0] ?? 0;
-  const minor = versionParts[1] ?? 0;
-  const patch = versionParts[2] ?? 0;
-  if (isNaN(major) || isNaN(minor) || isNaN(patch)) {
-    throw new Error(
-      `[pi-research] Cannot parse pi-coding-agent version "${PI_VERSION}". ` +
-      `Please ensure pi-coding-agent is installed correctly.`,
-    );
+  // Two thresholds, not one — see src/core/pi-version.ts. Below the floor the APIs
+  // we call do not exist, so we refuse. Above the last TESTED line we warn and
+  // continue: pi is pre-1.0, a minor bump can break anything under semver (0.83.0
+  // already extended the ResourceLoader contract), and our own dependency range
+  // cannot constrain the host at all when running as an extension.
+  const compat = checkPiCompatibility(PI_VERSION);
+  if (compat.fatal) {
+    throw new Error(compat.message ?? `[pi-research] Unsupported pi-coding-agent version "${PI_VERSION}".`);
   }
-  const minMajor = 0, minMinor = 80, minPatch = 8;
-  const tooOld = major < minMajor
-    || (major === minMajor && minor < minMinor)
-    || (major === minMajor && minor === minMinor && patch < minPatch);
-  if (tooOld) {
-    throw new Error(
-      `[pi-research] pi-coding-agent v${PI_VERSION} is too old. ` +
-      `Requires v${minMajor}.${minMinor}.${minPatch}+. Please update pi-coding-agent.`,
-    );
+  if (compat.message) {
+    logger.warn(compat.message);
   }
 
   // Re-register the beforeExit safety net (deactivate() strips event listeners during reload).

package/src/infrastructure/browser/browser-client.ts

@@ -7,13 +7,69 @@
 
 import * as http from 'node:http';
 import type { Config } from '../../config.ts';
+import { getConfig } from '../../config.ts';
 import type { SearchResult } from '../../web-research/types.ts';
 import type { IScheduler } from '../../core/interfaces/scheduler-interfaces.ts';
 import { logger } from '../../logger.ts';
 import { errorTracker } from '../../utils/error-tracker.ts';
+import { Utf8Body } from '../../utils/http-body.ts';
 import { getClientAgent } from './client-agent.ts';
 import type { NodeError } from '../../types/index.ts';
 
+/**
+ * Client-side patience margin on top of the leader's own task budget. The leader
+ * already bounds each task (nav budget + queue-wait margin) and answers with the
+ * more informative in-band timeout; the follower only needs headroom for the HTTP
+ * hop and leader-side dispatch, so its own timer never answers first.
+ */
+const CLIENT_PATIENCE_MARGIN_MS = 15_000;
+
+/**
+ * Absolute ceiling on any follower request, so a wedged-but-listening leader
+ * still fails in bounded time. Sits above the largest configurable leader budget
+ * (120s nav + 120s task margin) plus the patience margin, so it only binds when
+ * config is out of range. A DEAD leader is not this timer's job — its socket
+ * fails fast with ECONNREFUSED/ECONNRESET.
+ */
+const CLIENT_TIMEOUT_CAP_MS = 300_000;
+
+/**
+ * Mirror of the leader's fixed healthcheck budget in
+ * BrowserTaskScheduler.runHealthCheck (45s probe deadline + 60s queue-wait
+ * margin) — not config-derived there either.
+ */
+const HEALTHCHECK_LEADER_BUDGET_MS = 45_000 + 60_000;
+
+/**
+ * Per-operation follower timeout: the leader's own budget for that task kind
+ * plus a patience margin, bounded by an absolute cap.
+ *
+ * Invariant: the follower is at least as patient as the leader. The old flat 60s
+ * undercut the leader's healthcheck budget (105s) and config-driven search/scrape
+ * budgets (up to 130s+ within schema bounds), and the client-timeout text matches
+ * isTaskTimeoutError, so retry gates skipped it — long tasks failed client-side,
+ * unretried, while the leader was still working on them.
+ */
+export function resolveClientRequestTimeoutMs(operation: string, config?: Config): number {
+    const cfg = config ?? getConfig();
+    let leaderBudgetMs: number;
+    switch (operation) {
+        case 'search':
+            // BrowserTaskScheduler.runSearch: SEARCH_TIMEOUT_MS + BROWSER_TASK_TIMEOUT_MS.
+            leaderBudgetMs = cfg.SEARCH_TIMEOUT_MS + cfg.BROWSER_TASK_TIMEOUT_MS;
+            break;
+        case 'browser-task':
+            // BrowserTaskScheduler.runScrape: SCRAPE_TIMEOUT_MS + BROWSER_TASK_TIMEOUT_MS.
+            leaderBudgetMs = cfg.SCRAPE_TIMEOUT_MS + cfg.BROWSER_TASK_TIMEOUT_MS;
+            break;
+        default:
+            // healthcheck, plus any future/unknown path: the largest fixed budget.
+            leaderBudgetMs = HEALTHCHECK_LEADER_BUDGET_MS;
+            break;
+    }
+    return Math.min(CLIENT_TIMEOUT_CAP_MS, leaderBudgetMs + CLIENT_PATIENCE_MARGIN_MS);
+}
+
 /**
  * HTTP client that communicates with a remote scheduler.
  * Used when this process is not the leader.
@@ -21,12 +77,19 @@ import type { NodeError } from '../../types/index.ts';
 export class BrowserClient implements IScheduler {
     private readonly authSecret: string;
 
+    /** The leader port this client was built for — lets the herd-guard cooldown
+     * verify the cached handle still targets the REGISTERED leader, not a
+     * predecessor that died inside the cooldown window. */
+    get targetPort(): number {
+        return this.port;
+    }
+
     constructor(private readonly port: number, authSecret?: string) {
         this.authSecret = authSecret ?? process.env['PI_BROWSER_AUTH_SECRET'] ?? '';
         logger.log(`[BrowserClient] Connecting to global scheduler at http://127.0.0.1:${port}`);
     }
 
-    private async request<T>(path: string, data: any, signal?: AbortSignal): Promise<T> {
+    private async request<T>(path: string, data: any, signal?: AbortSignal, config?: Config): Promise<T> {
         const start = Date.now();
         // Extract operation from path for error tracking
         const operation = path.includes('/search') ? 'search' :
@@ -35,8 +98,8 @@ export class BrowserClient implements IScheduler {
 
         return new Promise((resolve, reject) => {
             const agent = getClientAgent();
-            // 60s timeout for client requests (1/3 of original 180s)
-            const timeoutMs = 60000;
+            // Config-derived per task kind: leader budget + margin, capped.
+            const timeoutMs = resolveClientRequestTimeoutMs(operation, config);
             let resolved = false;
             const controller = new AbortController();
             
@@ -93,8 +156,11 @@ export class BrowserClient implements IScheduler {
                 // when headers arrive, but the body is still streaming — clearing
                 // now would let a stalled body hang forever and make an external
                 // abort a no-op. Keep both armed until 'end' or 'error'.
-                let body = '';
-                res.on('data', chunk => body += chunk);
+                // This response carries scraped page content, so per-chunk decoding
+                // would corrupt every non-ASCII page that exceeds one chunk. Collect
+                // bytes and decode once. See Utf8Body.
+                const collected = new Utf8Body();
+                res.on('data', (chunk: Buffer) => collected.push(chunk));
                 res.on('end', () => {
                     if (resolved) return;
                     resolved = true;
@@ -102,7 +168,7 @@ export class BrowserClient implements IScheduler {
                     abortCleanup?.();
                     const duration = Date.now() - start;
                     try {
-                        const parsed = JSON.parse(body);
+                        const parsed = JSON.parse(collected.toString());
                         if (res.statusCode === 503 && parsed?.error === 'draining') {
                             // Planned leadership handover, not a fault. Distinct message so
                             // isServerDrainingError can classify it: retry paths treat it as
@@ -135,7 +201,8 @@ export class BrowserClient implements IScheduler {
                         }
                     } catch (_e) {
                         // FIX (#23): Truncate response body in error to prevent data leakage
-                        const preview = body.length > 200 ? body.slice(0, 200) + '...' : body;
+                        const raw = collected.toString();
+                        const preview = raw.length > 200 ? raw.slice(0, 200) + '...' : raw;
                         const error = new Error(`Failed to parse response (status ${res.statusCode}): ${preview}`);
                         errorTracker.trackError(error, {
                             component: 'browser-manager',
@@ -199,16 +266,16 @@ export class BrowserClient implements IScheduler {
         });
     }
 
-    async runSearch(query: string, _config?: Config, signal?: AbortSignal): Promise<SearchResult[]> {
-        return this.request('/search', { query }, signal);
+    async runSearch(query: string, config?: Config, signal?: AbortSignal): Promise<SearchResult[]> {
+        return this.request('/search', { query }, signal, config);
     }
 
-    async runScrape(url: string, _config?: Config, signal?: AbortSignal): Promise<any> {
-        return this.request('/scrape', { url }, signal);
+    async runScrape(url: string, config?: Config, signal?: AbortSignal): Promise<any> {
+        return this.request('/scrape', { url }, signal, config);
     }
 
-    async runHealthCheck(_config?: Config, signal?: AbortSignal): Promise<{ success: boolean }> {
-        return this.request('/healthcheck', {}, signal);
+    async runHealthCheck(config?: Config, signal?: AbortSignal): Promise<{ success: boolean }> {
+        return this.request('/healthcheck', {}, signal, config);
     }
 
     async shutdown() {

package/src/infrastructure/browser/browser-error-utils.ts

@@ -115,7 +115,12 @@ export function isPoolShutdownError(error: unknown): boolean {
         // classifier matched it, so the first attempt rethrew instead of retrying —
         // and auto-recovery fires only after 3 consecutive worker failures, i.e.
         // exactly when a burst of tasks is in flight and would all die together.
-        err.message.includes('Worker pool is being reset')
+        err.message.includes('Worker pool is being reset') ||
+        // poolifier's wording once destroy() has COMPLETED (vs "destroying pool"
+        // while it is in progress). A queued closure holding a pool captured before
+        // an auto-recovery destroy dispatches into exactly this window; it is the
+        // same transient swap the "being reset" string covers, not a hard fault.
+        err.message.includes('Cannot execute a task on not started pool')
     );
 }
 

package/src/infrastructure/browser/browser-server.ts

@@ -1,13 +1,14 @@
 import * as http from 'node:http';
 import * as crypto from 'node:crypto';
 import { logger } from '../../logger.ts';
+import { Utf8Body } from '../../utils/http-body.ts';
 import type { SearchResult } from '../../web-research/types.ts';
 import { isCloudflareBlockError, isPoolShutdownError } from './browser-error-utils.ts';
 
 export interface BrowserServerOptions {
-    onSearch: (query: string) => Promise<SearchResult[]>;
-    onScrape: (url: string) => Promise<any>;
-    onHealthCheck: () => Promise<{ success: boolean }>;
+    onSearch: (query: string, signal?: AbortSignal) => Promise<SearchResult[]>;
+    onScrape: (url: string, signal?: AbortSignal) => Promise<any>;
+    onHealthCheck: (signal?: AbortSignal) => Promise<{ success: boolean }>;
 }
 
 /**
@@ -92,6 +93,12 @@ export class BrowserServer {
                 const expected = Buffer.from(getOrCreateAuthSecret(), 'utf8');
                 const actual = Buffer.from(authHeader ?? '', 'utf8');
                 if (actual.length !== expected.length || !crypto.timingSafeEqual(actual, expected)) {
+                    // Drain the request before answering (mirrors the embedding
+                    // server's 403 path): without it a still-arriving body leaves
+                    // the request half-read and Node destroys the socket after the
+                    // response flush, so the client can see ECONNRESET instead of
+                    // the status.
+                    req.resume();
                     res.writeHead(403, { 'Content-Type': 'application/json' });
                     res.end(JSON.stringify({ error: 'Unauthorized' }));
                     return;
@@ -103,6 +110,7 @@ export class BrowserServer {
                 // stops the client reusing this socket for a retry that would
                 // only 503 again.
                 if (this.draining) {
+                    req.resume(); // drain before answering — see the 403 path
                     res.writeHead(503, {
                         'Content-Type': 'application/json',
                         'Connection': 'close',
@@ -112,18 +120,34 @@ export class BrowserServer {
                 }
 
                 if (req.method !== 'POST') {
+                    req.resume(); // drain before answering — see the 403 path
                     res.writeHead(405);
                     res.end('Method Not Allowed');
                     return;
                 }
 
-                let body = '';
+                // Follower cancellation must cross this HTTP hop: when the
+                // client's socket dies before the response completes (the
+                // follower aborted its request), the leader-side task previously
+                // kept its queue slot and worker page until its full timeout.
+                // Abort the task the moment the connection tears down. 'close'
+                // also fires after a normally completed response, so gate on
+                // writableEnded to abort only a premature teardown.
+                const requestAbort = new AbortController();
+                res.on('close', () => {
+                    if (!res.writableEnded) requestAbort.abort();
+                });
+
+                // Decoded once at 'end' rather than per chunk: `body += chunk`
+                // mangles any multi-byte character that straddles a chunk boundary.
+                // See Utf8Body.
+                const collected = new Utf8Body();
                 let oversized = false;
                 const MAX_BODY_SIZE = 10 * 1024 * 1024; // 10MB limit
 
-                req.on('data', chunk => {
-                    body += chunk;
-                    if (body.length > MAX_BODY_SIZE) {
+                req.on('data', (chunk: Buffer) => {
+                    collected.push(chunk);
+                    if (collected.byteLength > MAX_BODY_SIZE) {
                         oversized = true;
                         req.destroy(new Error('Payload too large'));
                     }
@@ -144,18 +168,18 @@ export class BrowserServer {
 
                 req.on('end', async () => {
                     try {
-                        const data = JSON.parse(body);
+                        const data = JSON.parse(collected.toString());
                         let result: any;
 
                         switch (req.url) {
                             case '/search':
-                                result = await this.options.onSearch(data.query);
+                                result = await this.options.onSearch(data.query, requestAbort.signal);
                                 break;
                             case '/scrape':
-                                result = await this.options.onScrape(data.url);
+                                result = await this.options.onScrape(data.url, requestAbort.signal);
                                 break;
                             case '/healthcheck':
-                                result = await this.options.onHealthCheck();
+                                result = await this.options.onHealthCheck(requestAbort.signal);
                                 break;
                             default:
                                 res.writeHead(404);
@@ -169,7 +193,12 @@ export class BrowserServer {
                         // A Cloudflare/bot challenge is an EXPECTED scrape outcome, not a
                         // server fault — log it at WARN so it doesn't inflate ERROR counts.
                         // Everything else is a genuine request-handling error.
-                        if (isCloudflareBlockError(error)) {
+                        if (requestAbort.signal.aborted) {
+                            // The client disconnected before completion; the abort above
+                            // cancelled the leader-side task and nobody is waiting for
+                            // this reply — expected teardown, not a server fault.
+                            logger.debug('[BrowserServer] Client disconnected mid-request; task aborted:', error instanceof Error ? error.message : String(error));
+                        } else if (isCloudflareBlockError(error)) {
                             logger.warn('[BrowserServer] Request blocked by bot protection:', error instanceof Error ? error.message : String(error));
                         } else if (isPoolShutdownError(error)) {
                             // Pool destroyed mid-request during quit/SIGTERM teardown — expected,