harper 5.1.20 → 5.2.0-alpha.5

package/server/static.ts

@@ -2,6 +2,8 @@ import { realpathSync, existsSync } from 'node:fs';
 import { join } from 'node:path';
 import { Scope } from '../components/Scope';
 import { resolveBaseURLPath } from '../components/resolveBaseURLPath.ts';
+import { convertToMS } from '../utility/common_utils.ts';
+import { isMatch } from 'micromatch';
 import send from 'send';
 
 /**
@@ -12,13 +14,134 @@ import send from 'send';
  * - `index`: If enabled, it will serve `index.html` files from directories.
  * - `extensions`: An array of file extensions to try when serving files. If a file is not found, it will try appending each extension in order. For example, if set to `['html'], and the request is `/page`, it will try `/page.html` if `/page` is not found.
  * - `fallthrough`: If true, it will fall through to the next handler if the file is not found. If false, it will return a 404 error.
+ * - `maxAge`: Freshness lifetime for served files — a number of seconds or a duration string
+ *   (`'5m'`, `'1d'`). Emitted as `Cache-Control: public, max-age=<seconds>`. Defaults to 0
+ *   (revalidate every request via the ETag/Last-Modified that are always emitted).
+ * - `immutable`: If true, adds the `immutable` directive to `Cache-Control` — for content-hashed
+ *   assets that never change under the same URL. Requires `maxAge` to be meaningful.
+ * - `cacheControl`: Full `Cache-Control` override string (takes precedence over `maxAge`/`immutable`),
+ *   or `false` to suppress the header entirely. Static files are served before authentication, so
+ *   they are public by construction — do not put per-user content behind this handler.
+ * - `cacheOverrides`: A map of glob pattern → partial cache options (`maxAge` / `immutable` /
+ *   `cacheControl`), letting specific files opt out of the top-level defaults. The typical case is
+ *   long-lived `immutable` defaults for content-hashed assets while `index.html` gets a short window
+ *   or `stale-while-revalidate`. Patterns are matched (via `micromatch`, same engine as `files`)
+ *   against the mount-relative URL path **and** the served file's basename — so `index.html` also
+ *   targets the directory-index (`/`) serve. Entries are tested in config order and the first match
+ *   wins; each is a partial (keys present replace the default, absent keys inherit), with the same
+ *   `cacheControl`-beats-`maxAge`/`immutable` precedence as the top level. Example:
+ *   ```yaml
+ *   static:
+ *     files: 'web/**'
+ *     maxAge: 1y
+ *     immutable: true
+ *     cacheOverrides:
+ *       'index.html': { cacheControl: 'public, max-age=0, stale-while-revalidate=60' }
+ *       '*.html': { maxAge: 5m, immutable: false }
+ *   ```
  * - `notFound`: Can be specified as a string to serve a custom 404 page, or an object with `file` and `statusCode` properties to serve a custom file with a specific status code. This is useful for hosting SPAs that use client-side routing. Make sure to set `fallthrough` to `false`!
+ * - `before` / `after`: Position this handler in the HTTP middleware chain relative to another named
+ *   handler. By default the handler runs `before: 'authentication'` — and therefore before the REST
+ *   handler — so plain file requests skip credential parsing. That default means a `fallthrough: false`
+ *   catch-all answers GETs for exported REST resources too; an SPA with history-mode routing should set
+ *   `after: 'rest'` so the API is matched first and only unmatched URLs receive the `notFound` fallback.
+ *   `before: false` clears the default without adding a new constraint (registration order applies).
+ *   Handler names are the component config keys as registered (e.g. `rest`, not the legacy `REST` alias);
+ *   a name that matches no registered handler is ignored, with a warning logged by the middleware chain.
+ *   Ordering is applied when the component loads; changing `before`/`after` triggers a component restart.
  *
  * This plugin dynamically updates its behavior based on the current configuration file. Users can make updates and immediately see the changes reflect in the next request.
  *
  * Updates to the `files` option will clear the in-memory maps and allow them to regenerate based on the new configuration (since the default EntryHandler will regenerate anyways).
  * Updates to `urlPath` request a restart: the HTTP route mount is registered once at load and cannot be re-registered on a live server (#1583).
  */
+/**
+ * Resolve the effective cache-header inputs for a given served file: the live top-level
+ * `maxAge`/`immutable`/`cacheControl` options, with the first matching `cacheOverrides` entry layered
+ * on top (a partial — keys present replace the default, absent keys inherit). Patterns are matched
+ * (via `micromatch`, same engine as `files`) against the mount-relative URL path and the file's
+ * basename, so `index.html` also targets the directory-index (`/`) serve.
+ */
+function resolveCacheOptions(scope: Scope, urlKey: string, basename: string) {
+	let maxAge = scope.options.get(['maxAge']);
+	let immutable = scope.options.get(['immutable']);
+	let cacheControl = scope.options.get(['cacheControl']);
+
+	const overrides = scope.options.get(['cacheOverrides']);
+	if (overrides !== undefined) {
+		if (typeof overrides !== 'object' || overrides === null || Array.isArray(overrides)) {
+			throw new Error(`Invalid cacheOverrides option: ${overrides}. Must be a map of glob pattern to cache options.`);
+		}
+		for (const pattern of Object.keys(overrides)) {
+			if (isMatch(urlKey, pattern) || isMatch(basename, pattern)) {
+				const override = overrides[pattern];
+				if (typeof override !== 'object' || override === null || Array.isArray(override)) {
+					throw new Error(
+						`Invalid cacheOverrides['${pattern}'] value: ${override}. Must be an object with maxAge/immutable/cacheControl.`
+					);
+				}
+				// partial merge: only keys present in the override replace the top-level default
+				if ('maxAge' in override) maxAge = override.maxAge;
+				if ('immutable' in override) immutable = override.immutable;
+				if ('cacheControl' in override) cacheControl = override.cacheControl;
+				break; // first match wins
+			}
+		}
+	}
+
+	immutable = immutable ?? false;
+	if (maxAge !== undefined && typeof maxAge !== 'number' && typeof maxAge !== 'string') {
+		throw new Error(`Invalid maxAge option: ${maxAge}. Must be a number of seconds or a duration string like '5m'.`);
+	}
+	const maxAgeMs = maxAge === undefined ? 0 : convertToMS(maxAge);
+	if (Number.isNaN(maxAgeMs)) {
+		throw new Error(`Invalid maxAge option: ${maxAge}. Must be a number of seconds or a duration string like '5m'.`);
+	}
+	if (typeof immutable !== 'boolean') {
+		throw new Error(`Invalid immutable option: ${immutable}. Must be a boolean.`);
+	}
+	if (cacheControl !== undefined && typeof cacheControl !== 'string' && cacheControl !== false) {
+		throw new Error(`Invalid cacheControl option: ${cacheControl}. Must be a string or false.`);
+	}
+	const customCacheControl = typeof cacheControl === 'string' ? cacheControl : undefined;
+	return { cacheControlDisabled: cacheControl === false, maxAgeMs, immutable, customCacheControl };
+}
+
+/**
+ * Serve a file through `send`, applying the plugin's cache-header options (read live from the
+ * component config, like `fallthrough`, and layered with any matching `cacheOverrides` entry).
+ * `cacheControl` as a string overrides `maxAge`/`immutable` via send's `headers` event;
+ * `cacheControl: false` suppresses the header entirely. Applied only to the main file serve — the
+ * `notFound` fallback keeps send's default `max-age=0`, which is the right policy for SPA index
+ * fallbacks.
+ */
+function serveFile(req, path: string, scope: Scope) {
+	// The staticFiles map keys are the mount-relative URL path (leading slash stripped for matching);
+	// for a directory-index serve req.pathname is the directory, so also match the served basename.
+	const urlKey = typeof req.pathname === 'string' ? req.pathname.replace(/^\//, '') : '';
+	const basename = path.slice(Math.max(path.lastIndexOf('/'), path.lastIndexOf('\\')) + 1);
+	const { cacheControlDisabled, maxAgeMs, immutable, customCacheControl } = resolveCacheOptions(
+		scope,
+		urlKey,
+		basename
+	);
+
+	const stream = send(req, path, {
+		// suppress send's own header when we set a full override below (or when disabled)
+		cacheControl: cacheControlDisabled || customCacheControl !== undefined ? false : true,
+		maxAge: maxAgeMs,
+		immutable,
+	});
+	// an empty-string override intentionally behaves like `false` (send's header is suppressed
+	// above and no override is written)
+	if (customCacheControl) {
+		stream.on('headers', (response) => {
+			response.setHeader('Cache-Control', customCacheControl);
+		});
+	}
+	return stream;
+}
+
 export function handleApplication(scope: Scope) {
 	// in-memory map of static files
 	// keys are the URL paths relative to the mount base, values are the absolute paths to the files
@@ -30,6 +153,34 @@ export function handleApplication(scope: Scope) {
 	// with the registered route (#1583).
 	const baseURLPath = resolveBaseURLPath(scope.pluginName, (scope.options.getAll() as any)?.urlPath);
 
+	// A bare `before:` / `after:` key in YAML parses as null — treat it as unset, like before this
+	// option was validated.
+	const before = scope.options.get(['before']) ?? undefined;
+	const after = scope.options.get(['after']) ?? undefined;
+	validateOrderingOption('before', before, true);
+	validateOrderingOption('after', after, false);
+	// Default to the pre-authentication hoist only when no ordering was configured at all.
+	const noOrderingConfigured = before === undefined && after === undefined;
+
+	// With the default ordering this handler answers unmatched GETs ahead of the REST handler, so a
+	// `fallthrough: false` catch-all makes any exported REST resources unreachable over GET.
+	// Reads the live option values (not the registration-time ones above): a config save can change
+	// the ordering options together with `fallthrough`, and this re-runs from the change listener.
+	const warnIfBlockingRest = () => {
+		const liveBefore = scope.options.get(['before']) ?? undefined;
+		const liveAfter = scope.options.get(['after']) ?? undefined;
+		if (
+			liveAfter === undefined &&
+			(liveBefore === undefined || liveBefore === 'authentication') &&
+			scope.options.get(['fallthrough']) === false
+		) {
+			scope.logger.warn(
+				`The static handler runs before authentication and REST by default, so \`fallthrough: false\` answers every unmatched GET itself — including GETs for any exported REST resources. If this application serves an API, add \`after: 'rest'\` to the static options so API requests are matched first, or remove \`fallthrough: false\`.`
+			);
+		}
+	};
+	warnIfBlockingRest();
+
 	scope.options.on('change', (key) => {
 		if (key[0] === 'files') {
 			// If the files option changes, clear the maps and let the entry handler regenerate them
@@ -43,6 +194,16 @@ export function handleApplication(scope: Scope) {
 			scope.requestRestart();
 			return;
 		}
+		if (key[0] === 'fallthrough') {
+			warnIfBlockingRest();
+			return;
+		}
+		// `before`/`after` are consumed once at registration; the middleware chain can only pick
+		// up a new ordering by reloading the component. (Scope's own auto-restart on option
+		// changes is bypassed once a plugin registers its own 'change' listener, as we do above.)
+		if (key[0] === 'before' || key[0] === 'after') {
+			scope.requestRestart();
+		}
 	});
 
 	// Handle entry events for the default entry handler based on the `files` and `urlPath` options
@@ -171,7 +332,7 @@ export function handleApplication(scope: Scope) {
 				// The benefit to using `send` is that it handles a lot of edge cases and headers for us.
 				return {
 					handlesHeaders: true,
-					body: send(req, realpathSync(staticFile)),
+					body: serveFile(req, realpathSync(staticFile), scope),
 				};
 			}
 
@@ -206,7 +367,24 @@ export function handleApplication(scope: Scope) {
 				body: send(req, realpathSync(notFoundPath)),
 			};
 		},
-		{ before: (scope.options.get(['before']) as string) ?? 'authentication' }
+		{
+			// `after` (e.g. `after: 'rest'`) must suppress the default pre-authentication hoist —
+			// combining the two constraints would be a cycle, which falls back to registration order.
+			before: typeof before === 'string' ? before : noOrderingConfigured ? 'authentication' : undefined,
+			after: after as string | undefined,
+		}
+	);
+}
+
+function validateOrderingOption(
+	name: string,
+	value: any,
+	allowFalse: boolean
+): asserts value is undefined | string | false {
+	if (value === undefined || (typeof value === 'string' && value.length > 0)) return;
+	if (allowFalse && value === false) return;
+	throw new Error(
+		`Invalid \`${name}\` option: ${value}. Must be the name of another handler${allowFalse ? ', or false to clear the default ordering' : ''}.`
 	);
 }
 

package/server/status/index.ts

@@ -5,6 +5,9 @@ import { validateStatus } from '../../validation/statusValidator.ts';
 import { type StatusId, type StatusValueMap, type StatusRecord, DEFAULT_STATUS_ID } from './definitions.ts';
 import { internal as statusInternal, type AggregatedComponentStatus } from '../../components/status/index.ts';
 import { restartNeeded } from '../../components/requestRestart.ts';
+import { sendItcEvent } from '../threads/itc.js';
+import { onMessageByType, workers } from '../threads/manageThreads.js';
+import { ITC_EVENT_TYPES, THREAD_TYPES } from '../../utility/hdbTerms.ts';
 
 export { clearStatus as clear, getStatus as get, setStatus as set };
 
@@ -18,6 +21,9 @@ const { HTTP_STATUS_CODES } = hdbErrors;
 // For direct function calls, we don't need the operation fields
 type StatusRequestBody = {
 	id: StatusId;
+	// Opt in to the resolved HTTP/upgrade/WebSocket middleware chains in the aggregated (no-id)
+	// response (#1573). Off by default so routine polling avoids the cross-thread lookup.
+	middleware?: boolean;
 };
 
 type StatusWriteRequestBody<T extends StatusId = StatusId> = {
@@ -76,9 +82,69 @@ interface AllStatusSummary {
 	systemStatus: Promise<AsyncIterable<StatusRecord>>;
 	componentStatus: AggregatedComponentStatusWithName[];
 	restartRequired: boolean;
+	// Only present when the request opts in with `middleware: true`.
+	middlewareChains?: MiddlewareChainsSummary | null;
 }
 
-async function getAllStatus(): Promise<AllStatusSummary> {
+type MiddlewareChainsSummary = ReturnType<typeof import('../http.ts').describeMiddlewareChains>;
+
+let nextChainsRequestId = 1;
+let chainsResponseListenerAttached = false;
+const pendingChainsRequests = new Map<number, (chains: MiddlewareChainsSummary) => void>();
+
+function attachChainsResponseListener(): void {
+	if (chainsResponseListenerAttached) return;
+	onMessageByType(ITC_EVENT_TYPES.MIDDLEWARE_CHAINS_RESPONSE, ({ message }: any) => {
+		const resolve = pendingChainsRequests.get(message.requestId);
+		if (resolve) {
+			pendingChainsRequests.delete(message.requestId);
+			resolve(message.chains);
+		}
+	});
+	chainsResponseListenerAttached = true;
+}
+
+// App HTTP middleware is only registered on worker threads, so when get_status runs on the main
+// thread we ask an HTTP worker for its resolved chains (all workers register identically). Returns
+// null if no worker answers within the timeout — mirrors queryWorkerForOpenApi in operationsServer.
+function queryWorkerForMiddlewareChains(): Promise<MiddlewareChainsSummary | null> {
+	attachChainsResponseListener();
+	const requestId = nextChainsRequestId++;
+	return new Promise((resolve) => {
+		const timeoutHandle = setTimeout(() => {
+			pendingChainsRequests.delete(requestId);
+			resolve(null);
+		}, 5000);
+		pendingChainsRequests.set(requestId, (chains) => {
+			clearTimeout(timeoutHandle);
+			resolve(chains);
+		});
+		sendItcEvent({ type: ITC_EVENT_TYPES.MIDDLEWARE_CHAINS_REQUEST, message: { requestId } }).catch(() => {
+			clearTimeout(timeoutHandle);
+			pendingChainsRequests.delete(requestId);
+			resolve(null);
+		});
+	});
+}
+
+// Introspect the resolved HTTP/upgrade/WebSocket middleware order (#1573). In a multi-worker
+// deployment the app middleware is registered on the HTTP worker threads while the main thread
+// carries only the operations-API middleware, so when an HTTP worker exists we fetch the chains from
+// one over ITC. With no HTTP worker this thread is the app server itself (single-thread mode, or a
+// worker serving the request) and reports locally. Job workers don't serve HTTP, so they're ignored.
+async function getMiddlewareChains(): Promise<MiddlewareChainsSummary | null> {
+	try {
+		if (workers.some((worker: { name?: string }) => worker.name === THREAD_TYPES.HTTP))
+			return await queryWorkerForMiddlewareChains();
+		const { describeMiddlewareChains } = await import('../http.ts');
+		return describeMiddlewareChains();
+	} catch (error) {
+		statusLogger.debug?.('getMiddlewareChains failed', error);
+		return null;
+	}
+}
+
+async function getAllStatus(includeMiddleware = false): Promise<AllStatusSummary> {
 	statusLogger.debug?.('getAllStatus');
 	const statusRecords = getStatusTable().search([]);
 
@@ -94,17 +160,19 @@ async function getAllStatus(): Promise<AllStatusSummary> {
 	// Get restart flag status
 	const restartRequired = restartNeeded();
 
-	return {
+	const summary: AllStatusSummary = {
 		systemStatus: statusRecords as Promise<AsyncIterable<StatusRecord>>,
 		componentStatus: componentStatusArray,
 		restartRequired,
 	};
+	if (includeMiddleware) summary.middlewareChains = await getMiddlewareChains();
+	return summary;
 }
 
-function getStatus({ id }: Partial<StatusRequestBody>): Promise<StatusRecord | AllStatusSummary> {
+function getStatus({ id, middleware }: Partial<StatusRequestBody>): Promise<StatusRecord | AllStatusSummary> {
 	if (!id) {
 		statusLogger.debug?.('getStatus', 'all');
-		return getAllStatus();
+		return getAllStatus(middleware === true);
 	}
 
 	statusLogger.debug?.('getStatus', id);

package/server/threads/manageThreads.js

@@ -136,6 +136,8 @@ module.exports = {
 	setTerminateTimeout,
 	extendShutdownDeadline,
 	restoreShutdownDeadline,
+	registerWorkerDataProvider,
+	onThreadExit,
 	restartNumber: workerData?.restartNumber || 1,
 };
 
@@ -178,6 +180,59 @@ function setMainIsWorker(isWorker) {
 	module.exports.threadsHaveStarted();
 }
 let workerCount = 1; // should be assigned when workers are created
+
+// Every workerData key core itself produces or consumes — providers may not collide with these.
+// Covers the keys startWorker spreads below plus keys read elsewhere: `noServerStart` is set by
+// the embedding entry point (index.ts) and read by threadServer.js to skip startServers(); a
+// provider shadowing it would wedge HTTP worker startup.
+const RESERVED_WORKER_DATA_KEYS = [
+	'addPorts',
+	'addThreadIds',
+	'workerIndex',
+	'workerCount',
+	'name',
+	'restartNumber',
+	'ticketKeys',
+	'noServerStart',
+	'__proto__', // never a legitimate payload name; spread would define it as an own property
+];
+const workerDataProviders = new Map();
+/**
+ * Register a provider that contributes an extra `workerData` property to every worker spawned
+ * from this thread. `provider(options)` receives the startWorker options (`options.name` is the
+ * thread type, e.g. 'http' or 'job') and returns the value to place at `workerData[name]`, or
+ * undefined to skip that worker. Values must be structured-cloneable; a provider that throws or
+ * returns a non-cloneable value is logged and skipped so it can never break a spawn.
+ * Returns a function that unregisters the provider.
+ */
+function registerWorkerDataProvider(name, provider) {
+	if (RESERVED_WORKER_DATA_KEYS.includes(name) || workerDataProviders.has(name)) {
+		throw new Error(`workerData provider name '${name}' is already in use`);
+	}
+	if (typeof provider !== 'function') throw new Error('workerData provider must be a function');
+	workerDataProviders.set(name, provider);
+	return () => {
+		if (workerDataProviders.get(name) === provider) workerDataProviders.delete(name);
+	};
+}
+function collectProvidedWorkerData(options) {
+	if (workerDataProviders.size === 0) return undefined;
+	let provided;
+	for (const [name, provider] of workerDataProviders) {
+		try {
+			const value = provider(options);
+			if (value === undefined) continue;
+			// Use the clone, not the original: this both pre-flights cloneability (so a bad value
+			// can't break the Worker spawn) and detaches the payload from accessor-backed objects
+			// or later mutation that could still throw inside new Worker(). Null prototype so a
+			// provider name can never collide with Object.prototype members.
+			(provided ??= Object.create(null))[name] = structuredClone(value);
+		} catch (error) {
+			harperLogger.error(`workerData provider '${name}' failed and will be skipped for this worker:`, error);
+		}
+	}
+	return provided;
+}
 let ticketKeys;
 function getTicketKeys() {
 	if (ticketKeys) return ticketKeys;
@@ -212,6 +267,11 @@ listenersByType.set(hdbTerms.ITC_EVENT_TYPES.USER, null);
 listenersByType.set(hdbTerms.ITC_EVENT_TYPES.COMPONENT_STATUS_REQUEST, null);
 listenersByType.set(hdbTerms.ITC_EVENT_TYPES.RESOURCE_OPENAPI_REQUEST, null);
 listenersByType.set(hdbTerms.ITC_EVENT_TYPES.RESOURCE_OPENAPI_RESPONSE, null);
+listenersByType.set(hdbTerms.ITC_EVENT_TYPES.MIDDLEWARE_CHAINS_REQUEST, null);
+listenersByType.set(hdbTerms.ITC_EVENT_TYPES.MIDDLEWARE_CHAINS_RESPONSE, null);
+listenersByType.set(hdbTerms.ITC_EVENT_TYPES.OPERATION_REGISTERED, null);
+listenersByType.set(hdbTerms.ITC_EVENT_TYPES.OPERATION_EXECUTE_REQUEST, null);
+listenersByType.set(hdbTerms.ITC_EVENT_TYPES.OPERATION_EXECUTE_RESPONSE, null);
 
 function startWorker(path, options = {}) {
 	// Take a percentage of total memory to determine the max memory for each thread. The percentage is based
@@ -281,6 +341,7 @@ function startWorker(path, options = {}) {
 		argv: process.argv.slice(2),
 		// pass these in synchronously to the worker so it has them on startup:
 		workerData: {
+			...collectProvidedWorkerData(options),
 			addPorts: portsToSend,
 			addThreadIds: channelsToConnect.map((channel) => channel.existingPort.threadId),
 			workerIndex: options.workerIndex,
@@ -380,10 +441,16 @@ async function restartWorkers(
 		// make a copy of the workers before iterating them, as the workers array mutates a lot during this
 		let waitingToFinish = []; // promises for workers we have shut down and are waiting to exit
 		// We can only start the replacement *before* the old worker releases its port when the OS lets
-		// both listen on the same port at once (SO_REUSEPORT). Without that — Windows (no SO_REUSEPORT)
-		// and Bun — the replacement can't bind until the old worker exits, so there we keep the original
-		// ordering: shut the old worker down first, then start the replacement (an unavoidable brief gap).
-		const canPreStartReplacement = process.platform !== 'win32' && !isBun;
+		// both listen on the same port at once (SO_REUSEPORT). Without that — Windows (no SO_REUSEPORT),
+		// macOS (unreliable SO_REUSEPORT, so workers bind exclusively), and Bun — the replacement can't
+		// bind a port the old worker still holds: its EADDRINUSE would be swallowed and the port left
+		// unbound once the old worker exits (this silently killed worker-owned listeners like MQTT on
+		// macOS after every component-reload restart). So there we keep the original ordering: shut the
+		// old worker down first (server.close() releases its ports immediately), then start the
+		// replacement — an unavoidable brief gap, but only for worker-owned listeners, since the main
+		// thread keeps serving the HTTP ports throughout. This ordering is also what lets
+		// listenOnPorts() treat a dedicated listener's EADDRINUSE as an external conflict.
+		const canPreStartReplacement = process.platform !== 'win32' && process.platform !== 'darwin' && !isBun;
 		for (let worker of workers.slice(0)) {
 			if ((name && worker.name !== name) || worker.wasShutdown) continue; // filter by type, if specified
 			const overlapping = OVERLAPPING_RESTART_TYPES.indexOf(worker.name) > -1;
@@ -766,10 +833,36 @@ if (parentPort && workerData?.addPorts) {
 }
 module.exports.getThreadInfo = getThreadInfo;
 
+// Listeners notified when a connected thread's port closes (worker exit/restart), so
+// modules holding per-thread state (e.g. registeredOperations' registry and in-flight
+// forwards) can clean up.
+const threadExitListeners = [];
+function onThreadExit(listener) {
+	threadExitListeners.push(listener);
+}
+
+// Thread ids already reported to threadExitListeners, so a dead worker is only reported once
+// regardless of which of the two removal paths below observes it first. Node worker_threads
+// ids are monotonically increasing and never reused within a process, so this never needs
+// pruning (unbounded growth is one entry per worker restart over the process lifetime).
+const notifiedDeadThreadIds = new Set();
+function notifyThreadExit(deadThreadId) {
+	if (deadThreadId == null || notifiedDeadThreadIds.has(deadThreadId)) return;
+	notifiedDeadThreadIds.add(deadThreadId);
+	for (const listener of threadExitListeners) {
+		try {
+			listener(deadThreadId);
+		} catch (error) {
+			harperLogger.error(error);
+		}
+	}
+}
+
 function removePort(port, deadThreadId) {
 	const idx = connectedPorts.indexOf(port);
 	if (idx === -1) return;
 	connectedPorts.splice(idx, 1);
+	if (deadThreadId != null) notifyThreadExit(deadThreadId);
 	// Notify remaining peers to remove this dead sibling port. In Bun, sibling
 	// MessagePorts don't emit 'close' when a peer worker exits, so we broadcast
 	// a REMOVE_PORT message from here (which fires reliably on Worker 'exit')
@@ -804,6 +897,11 @@ function addPort(port, keepRef, isJobWorker) {
 			} else if (message.type === REMOVE_PORT) {
 				const idx = connectedPorts.findIndex((p) => p.threadId === message.threadId);
 				if (idx !== -1) connectedPorts.splice(idx, 1);
+				// A sibling's port-to-the-dead-worker can close (and broadcast this) before this
+				// thread's OWN port to that worker fires its 'close'/'exit' — at which point
+				// removePort() would no-op (already spliced) and threadExitListeners would never
+				// fire. Notify here too; notifyThreadExit dedupes so it isn't reported twice.
+				notifyThreadExit(message.threadId);
 			} else {
 				notifyMessageListeners(message, port);
 			}

package/server/threads/socketRouter.ts

@@ -18,7 +18,7 @@ if (isMainThread) {
 			harperLogger.disableStdio();
 			return;
 		}
-		console.error('uncaughtException', error);
+		console.error('uncaughtException', harperLogger.errorForLog(error));
 	});
 }
 
@@ -30,6 +30,10 @@ export async function startHTTPThreads(threadCount = 2, dynamicThreads?: boolean
 	startTransactionLogCooling();
 	try {
 		if (dynamicThreads) {
+			// No caller currently passes dynamicThreads. If one ever does, note that the main thread
+			// does not bind ports in this mode, so on platforms without SO_REUSEPORT (macOS/Windows)
+			// worker 0's exclusive HTTP bind would silently swallow an external EADDRINUSE — the
+			// external-conflict detection in listenOnPorts() assumes the main thread binds first.
 			startHTTPWorker(0, 1);
 		} else {
 			const { loadRootComponents } = require('../loadRootComponents.js');