@aws-blocks/core 0.1.10 → 0.1.11

package/dist/scripts/dev-server-reclaim.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=dev-server-reclaim.test.d.ts.map

package/dist/scripts/dev-server-reclaim.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dev-server-reclaim.test.d.ts","sourceRoot":"","sources":["../../src/scripts/dev-server-reclaim.test.ts"],"names":[],"mappings":""}

package/dist/scripts/dev-server-reclaim.test.js

@@ -0,0 +1,352 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+import { describe, it } from 'node:test';
+import assert from 'node:assert';
+import { createServer } from 'node:net';
+import { reclaimPort, reclaimMessage, evaluatePortBindRetry, createBindRetryController, DEFAULT_PORT_BIND_RETRY_POLICY, evaluateSingleton, parsePidRecord, isPidAlive, isPortOpen, } from './dev-server.js';
+import { findListenerPids, killListenerTree } from './process-tree.js';
+function getFreePort() {
+    return new Promise((resolve, reject) => {
+        const srv = createServer();
+        srv.on('error', reject);
+        srv.listen(0, '127.0.0.1', () => {
+            const addr = srv.address();
+            const port = typeof addr === 'object' && addr ? addr.port : 0;
+            srv.close(() => resolve(port));
+        });
+    });
+}
+// ── reclaimPort — startup / EADDRINUSE port reclaim policy ──────────────────
+// Fully injected: no real processes are spawned. `probe` is scripted to model
+// the port's open/closed state across the reclaim sequence, so we assert exactly
+// which signals are sent and when it gives up.
+describe('reclaimPort — frees a stale/orphaned port before startup', () => {
+    // reclaimPort probes the port up to three times: (1) initial check,
+    // (2) after the SIGTERM wait, (3) the final reclaimed? check.
+    function scriptedProbe(states) {
+        let i = 0;
+        return async () => states[Math.min(i++, states.length - 1)];
+    }
+    it('is a no-op when the port is already free (no discovery, no kills)', async () => {
+        const kills = [];
+        let listed = 0;
+        const result = await reclaimPort(3000, {
+            probe: scriptedProbe([false]),
+            listPids: () => { listed++; return [111]; },
+            killTree: (pid, sig) => kills.push([pid, sig]),
+            waitFree: async () => { },
+        });
+        assert.deepStrictEqual(result, { wasOpen: false, reclaimed: true, pids: [] });
+        assert.strictEqual(listed, 0, 'must not discover PIDs when the port is free');
+        assert.deepStrictEqual(kills, []);
+    });
+    it('SIGTERMs every listener and reports reclaimed when the port frees gracefully', async () => {
+        const kills = [];
+        const result = await reclaimPort(3100, {
+            // open, then free after SIGTERM, then still free at the final check
+            probe: scriptedProbe([true, false, false]),
+            listPids: () => [4242, 4243],
+            killTree: (pid, sig) => kills.push([pid, sig]),
+            waitFree: async () => { },
+        });
+        assert.deepStrictEqual(kills, [[4242, 'SIGTERM'], [4243, 'SIGTERM']]);
+        assert.deepStrictEqual(result, { wasOpen: true, reclaimed: true, pids: [4242, 4243] });
+    });
+    it('escalates to SIGKILL when the listener survives the graceful SIGTERM', async () => {
+        const kills = [];
+        const result = await reclaimPort(3000, {
+            // open, still open after SIGTERM, free after SIGKILL
+            probe: scriptedProbe([true, true, false]),
+            listPids: () => [777],
+            killTree: (pid, sig) => kills.push([pid, sig]),
+            waitFree: async () => { },
+        });
+        assert.deepStrictEqual(kills, [[777, 'SIGTERM'], [777, 'SIGKILL']]);
+        assert.strictEqual(result.reclaimed, true);
+    });
+    it('reports reclaimed:false when the port stays bound through SIGKILL', async () => {
+        const result = await reclaimPort(3000, {
+            probe: scriptedProbe([true, true, true]),
+            listPids: () => [777],
+            killTree: () => { },
+            waitFree: async () => { },
+        });
+        assert.strictEqual(result.wasOpen, true);
+        assert.strictEqual(result.reclaimed, false);
+    });
+    it('re-discovers listeners for the SIGKILL pass when the first discovery was empty', async () => {
+        const kills = [];
+        let call = 0;
+        const result = await reclaimPort(3000, {
+            probe: scriptedProbe([true, true, false]),
+            // First lsof pass momentarily returns nothing; second finds the owner.
+            listPids: () => (call++ === 0 ? [] : [999]),
+            killTree: (pid, sig) => kills.push([pid, sig]),
+            waitFree: async () => { },
+        });
+        assert.deepStrictEqual(kills, [[999, 'SIGKILL']]);
+        assert.strictEqual(result.reclaimed, true);
+    });
+    it('SIGKILLs the CURRENT owner, not the stale one, when the port changed hands during the wait', async () => {
+        // The original listener (111) is SIGTERM'd but exits, and a DIFFERENT process
+        // (222) grabs the port before the SIGKILL pass. The escalation must re-list
+        // and target the new owner (222) — never the stale pid (111) it already
+        // signalled — otherwise it SIGKILLs a dead pid and leaves the real owner.
+        const kills = [];
+        let call = 0;
+        const result = await reclaimPort(3000, {
+            // open, still open after SIGTERM (new owner now holds it), free after SIGKILL
+            probe: scriptedProbe([true, true, false]),
+            listPids: () => (call++ === 0 ? [111] : [222]),
+            killTree: (pid, sig) => kills.push([pid, sig]),
+            waitFree: async () => { },
+        });
+        assert.deepStrictEqual(kills, [[111, 'SIGTERM'], [222, 'SIGKILL']]);
+        assert.strictEqual(result.reclaimed, true);
+        // result.pids reflects the initial discovery (what we SIGTERM'd).
+        assert.deepStrictEqual(result.pids, [111]);
+    });
+    it('reports the port free once its real listener is reclaimed (real sockets, injected kill)', async () => {
+        const port = await getFreePort();
+        const srv = createServer((c) => c.destroy());
+        await new Promise((res) => srv.listen(port, '127.0.0.1', () => res()));
+        assert.strictEqual(await isPortOpen(port, '127.0.0.1'), true, 'port should be held before reclaim');
+        // Inject the "kill" as closing our test server so the real probe/waitFree
+        // path is exercised end-to-end without spawning an OS process.
+        let killed = false;
+        const result = await reclaimPort(port, {
+            probe: (p) => isPortOpen(p, '127.0.0.1'),
+            listPids: () => [process.pid],
+            killTree: () => { if (!killed) {
+                killed = true;
+                srv.close();
+            } },
+        });
+        assert.strictEqual(result.wasOpen, true);
+        assert.strictEqual(result.reclaimed, true);
+        assert.strictEqual(await isPortOpen(port, '127.0.0.1'), false, 'port should be free after reclaim');
+    });
+});
+// ── reclaimMessage — accurate startup reclaim-outcome messaging ──────────────
+describe('reclaimMessage — three-way reclaim outcome message', () => {
+    it('reports success when the port was reclaimed', () => {
+        const msg = reclaimMessage(3000, { wasOpen: true, reclaimed: true, pids: [] }, 'a stale/orphaned listener');
+        assert.match(msg, /Reclaimed port 3000 from a stale\/orphaned listener/);
+    });
+    it('names the holding pid(s) when reclaim failed but an owner is known', () => {
+        const msg = reclaimMessage(3100, { wasOpen: true, reclaimed: false, pids: [4242, 4243] }, 'a stale/orphaned dev server');
+        assert.match(msg, /Port 3100 held by pid\(s\) \[4242, 4243\]/);
+        assert.match(msg, /stop that process and retry/);
+    });
+    it('falls back to the generic message when reclaim failed with no owner PID', () => {
+        const msg = reclaimMessage(3000, { wasOpen: true, reclaimed: false, pids: [] }, 'a stale/orphaned listener');
+        assert.match(msg, /no owner PID found/);
+    });
+});
+// ── evaluatePortBindRetry — bounded :3000 EADDRINUSE retry ───────────────────
+describe('evaluatePortBindRetry — front-door bind retry budget', () => {
+    it('retries early attempts with a linear backoff', () => {
+        assert.deepStrictEqual(evaluatePortBindRetry(1), { retry: true, delayMs: 250 });
+        assert.deepStrictEqual(evaluatePortBindRetry(2), { retry: true, delayMs: 500 });
+    });
+    it('gives up (no retry) once the attempt budget is reached', () => {
+        const d = evaluatePortBindRetry(DEFAULT_PORT_BIND_RETRY_POLICY.maxAttempts);
+        assert.deepStrictEqual(d, { retry: false, delayMs: 0 });
+    });
+    it('honors a custom policy', () => {
+        const policy = { maxAttempts: 2, backoffMs: 100 };
+        assert.deepStrictEqual(evaluatePortBindRetry(1, policy), { retry: true, delayMs: 100 });
+        assert.deepStrictEqual(evaluatePortBindRetry(2, policy), { retry: false, delayMs: 0 });
+    });
+});
+// ── evaluateSingleton — singleton guard decision ────────────────────────────
+// Prevents two fighting supervisors while never blocking a `tsx watch` reload of
+// the SAME supervisor (same parent pid).
+describe('evaluateSingleton — one supervisor per port, hot-reload safe', () => {
+    const rec = (over = {}) => ({
+        pid: 1000,
+        ppid: 500,
+        port: 3000,
+        ...over,
+    });
+    const alive = () => true;
+    const dead = () => false;
+    it('proceeds when there is no (or a corrupt) pidfile', () => {
+        assert.deepStrictEqual(evaluateSingleton(null, { pid: 1, ppid: 2 }, true, alive), { action: 'proceed' });
+    });
+    it('proceeds on a tsx-watch relaunch of our own supervisor (same parent pid)', () => {
+        // New child, DIFFERENT own pid, but SAME watcher parent → not a competitor.
+        const d = evaluateSingleton(rec({ pid: 1000, ppid: 500 }), { pid: 1001, ppid: 500 }, true, alive);
+        assert.deepStrictEqual(d, { action: 'proceed' });
+    });
+    it('exits when a different, live supervisor is actually holding the port', () => {
+        const d = evaluateSingleton(rec({ pid: 1000, ppid: 500, port: 3000 }), { pid: 2000, ppid: 900 }, true, alive);
+        if (d.action !== 'exit')
+            assert.fail(`expected exit, got ${d.action}`);
+        assert.match(d.reason, /already running on :3000/);
+        assert.match(d.reason, /pid 1000/);
+    });
+    it('proceeds when the recorded owner is dead (stale pidfile), even if the port looks in use', () => {
+        const d = evaluateSingleton(rec({ pid: 1000, ppid: 500 }), { pid: 2000, ppid: 900 }, true, dead);
+        assert.deepStrictEqual(d, { action: 'proceed' });
+    });
+    it('proceeds when a different live owner is NOT holding the port (nothing to fight over)', () => {
+        const d = evaluateSingleton(rec({ pid: 1000, ppid: 500 }), { pid: 2000, ppid: 900 }, false, alive);
+        assert.deepStrictEqual(d, { action: 'proceed' });
+    });
+    it('treats the owner as alive when only its parent pid is still alive', () => {
+        // Recorded pid gone, but its parent (the watcher) is alive → owner alive.
+        const isAlive = (pid) => pid === 500;
+        const d = evaluateSingleton(rec({ pid: 1000, ppid: 500 }), { pid: 2000, ppid: 900 }, true, isAlive);
+        assert.strictEqual(d.action, 'exit');
+    });
+});
+// ── parsePidRecord ──────────────────────────────────────────────────────────
+describe('parsePidRecord — tolerant pidfile parsing', () => {
+    it('parses a well-formed record', () => {
+        assert.deepStrictEqual(parsePidRecord('{"pid":12,"ppid":3,"port":3000}'), { pid: 12, ppid: 3, port: 3000 });
+    });
+    it('returns null for empty / corrupt JSON', () => {
+        assert.strictEqual(parsePidRecord(''), null);
+        assert.strictEqual(parsePidRecord('not json'), null);
+        assert.strictEqual(parsePidRecord('{'), null);
+    });
+    it('returns null when required numeric fields are missing or wrong-typed', () => {
+        assert.strictEqual(parsePidRecord('{"pid":12,"ppid":3}'), null);
+        assert.strictEqual(parsePidRecord('{"pid":"12","ppid":3,"port":3000}'), null);
+        assert.strictEqual(parsePidRecord('{}'), null);
+    });
+});
+// ── isPidAlive ──────────────────────────────────────────────────────────────
+describe('isPidAlive — signal-0 liveness probe', () => {
+    it('reports alive when the probe signal succeeds', () => {
+        assert.strictEqual(isPidAlive(4242, () => { }), true);
+    });
+    it('reports dead on ESRCH', () => {
+        assert.strictEqual(isPidAlive(4242, () => { throw Object.assign(new Error('ESRCH'), { code: 'ESRCH' }); }), false);
+    });
+    it('reports alive on EPERM (exists, not ours to signal)', () => {
+        assert.strictEqual(isPidAlive(4242, () => { throw Object.assign(new Error('EPERM'), { code: 'EPERM' }); }), true);
+    });
+    it('rejects non-signalable pids (<= 1) without probing', () => {
+        let probed = false;
+        assert.strictEqual(isPidAlive(1, () => { probed = true; }), false);
+        assert.strictEqual(isPidAlive(0, () => { probed = true; }), false);
+        assert.strictEqual(probed, false);
+    });
+});
+// ── findListenerPids — port → listener PID discovery (injected runner) ───────
+describe('findListenerPids — lsof/netstat listener discovery', () => {
+    it('parses the bare PID list from `lsof -ti tcp:<port> -sTCP:LISTEN` on POSIX', () => {
+        const calls = [];
+        const pids = findListenerPids(3100, (cmd, args) => {
+            calls.push([cmd, args]);
+            return { stdout: '4242\n4243\n' };
+        }, 'linux');
+        assert.deepStrictEqual(pids, [4242, 4243]);
+        assert.deepStrictEqual(calls, [['lsof', ['-ti', 'tcp:3100', '-sTCP:LISTEN']]]);
+    });
+    it('dedups PIDs and drops non-signalable pids (<= 1)', () => {
+        const pids = findListenerPids(3000, () => ({ stdout: '5\n5\n1\n0\n7\n' }), 'linux');
+        assert.deepStrictEqual(pids, [5, 7]);
+    });
+    it('returns [] when nothing is listening (empty stdout / non-zero exit)', () => {
+        assert.deepStrictEqual(findListenerPids(3000, () => ({ stdout: '', status: 1 }), 'linux'), []);
+        assert.deepStrictEqual(findListenerPids(3000, () => ({ stdout: null }), 'linux'), []);
+    });
+    it('returns [] when the discovery command cannot run (never throws)', () => {
+        assert.deepStrictEqual(findListenerPids(3000, () => { throw new Error('ENOENT'); }, 'linux'), []);
+    });
+    it('parses LISTENING rows for the port from `netstat -ano` on Windows', () => {
+        const stdout = [
+            '  Proto  Local Address          Foreign Address        State           PID',
+            '  TCP    0.0.0.0:3100           0.0.0.0:0              LISTENING       4242',
+            '  TCP    0.0.0.0:3000           0.0.0.0:0              LISTENING       9001', // different port
+            '  TCP    127.0.0.1:3100         127.0.0.1:55123        ESTABLISHED     8888', // not listening
+        ].join('\r\n');
+        const pids = findListenerPids(3100, () => ({ stdout }), 'win32');
+        assert.deepStrictEqual(pids, [4242]);
+    });
+});
+// ── killListenerTree — reuses the frontend group-kill on a discovered PID ────
+describe('killListenerTree — reclaim reuses the process-group kill', () => {
+    it('group-signals the discovered PID on POSIX (negative pid)', () => {
+        const group = [];
+        killListenerTree(4242, 'SIGTERM', 'linux', (pid, sig) => group.push([pid, sig]));
+        assert.deepStrictEqual(group, [[-4242, 'SIGTERM']]);
+    });
+    it('reaps the tree via taskkill on Windows', () => {
+        const winPids = [];
+        let groupCalled = false;
+        killListenerTree(4242, 'SIGKILL', 'win32', () => { groupCalled = true; }, (pid) => { winPids.push(pid); return true; });
+        assert.strictEqual(groupCalled, false);
+        assert.deepStrictEqual(winPids, [4242]);
+    });
+});
+// ── createBindRetryController — :3000 EADDRINUSE retry wiring ─────────────────
+// Locks in the retry *wiring* the front-door robustness fix hinges on — the
+// 1-based attempt counter, the bounded decision, reclaim-result routing, and
+// retry scheduling — without a real socket. All effects are injected seams.
+describe('createBindRetryController — bounded EADDRINUSE reclaim-and-rebind', () => {
+    // setImmediate resolves after the microtask queue, so the controller's
+    // `void (async () => { await reclaim(); … scheduleRetry() })()` IIFE has run.
+    const flush = () => new Promise((r) => setImmediate(r));
+    function makeController(result = { wasOpen: true, reclaimed: true, pids: [] }, policy = DEFAULT_PORT_BIND_RETRY_POLICY) {
+        const rec = {
+            handler: () => { },
+            reclaimCalls: 0,
+            relistenCalls: 0,
+            exhaustedCalls: 0,
+            scheduled: [],
+            warnings: [],
+        };
+        rec.handler = createBindRetryController(3000, {
+            reclaim: async () => { rec.reclaimCalls += 1; return result; },
+            relisten: () => { rec.relistenCalls += 1; },
+            scheduleRetry: (fn, delayMs) => { rec.scheduled.push({ fn, delayMs }); },
+            onExhausted: () => { rec.exhaustedCalls += 1; },
+            warn: (m) => { rec.warnings.push(m); },
+        }, policy);
+        return rec;
+    }
+    it('reclaims and schedules a retry with linear backoff, invoking relisten on the scheduled callback', async () => {
+        const c = makeController();
+        c.handler(); // attempt 1
+        await flush();
+        assert.strictEqual(c.reclaimCalls, 1, 'reclaim runs on a retryable attempt');
+        assert.strictEqual(c.exhaustedCalls, 0);
+        assert.strictEqual(c.scheduled.length, 1, 'one retry scheduled');
+        assert.strictEqual(c.scheduled[0].delayMs, 250, 'delay = backoffMs * attempt (250*1)');
+        assert.match(c.warnings[0], /attempt 1\/3/);
+        // Firing the scheduled callback must re-attempt the bind (guards against a
+        // refactor dropping the onListening-bound relisten on the retry path).
+        assert.strictEqual(c.relistenCalls, 0, 'relisten deferred until the scheduled callback fires');
+        c.scheduled[0].fn();
+        assert.strictEqual(c.relistenCalls, 1);
+        c.handler(); // attempt 2
+        await flush();
+        assert.strictEqual(c.scheduled.length, 2);
+        assert.strictEqual(c.scheduled[1].delayMs, 500, 'delay = backoffMs * attempt (250*2)');
+        assert.match(c.warnings.at(-1) ?? '', /attempt 2\/3/);
+    });
+    it('gives up after the attempt budget — no reclaim, no retry scheduled, actionable message', async () => {
+        const c = makeController({ wasOpen: true, reclaimed: true, pids: [] }, { maxAttempts: 2, backoffMs: 100 });
+        c.handler(); // attempt 1 → retry
+        await flush();
+        c.handler(); // attempt 2 → budget reached
+        await flush();
+        assert.strictEqual(c.exhaustedCalls, 1, 'onExhausted fired exactly once at the budget');
+        assert.strictEqual(c.reclaimCalls, 1, 'no reclaim on the exhausted attempt (only the retryable one)');
+        assert.strictEqual(c.scheduled.length, 1, 'no retry scheduled after exhaustion');
+        assert.match(c.warnings.at(-1) ?? '', /still in use after 2/);
+    });
+    it('surfaces the holding pid(s) when a retry reclaim fails to free the port', async () => {
+        const c = makeController({ wasOpen: true, reclaimed: false, pids: [4242] });
+        c.handler(); // attempt 1 → retry; reclaim fails
+        await flush();
+        assert.ok(c.warnings.some((w) => /held by pid\(s\) \[4242\]/.test(w)), 'operator sees the pid-naming reclaim message, not just the generic banner');
+        // A failed reclaim still schedules the next attempt (the budget, not reclaim
+        // success, bounds the loop).
+        assert.strictEqual(c.scheduled.length, 1);
+    });
+});

package/dist/scripts/dev-server.d.ts

@@ -36,6 +36,26 @@ export interface DevServerOptions {
     /** Port the frontend dev server listens on. Default: 3100. */
     frontendPort?: number;
 }
+/**
+ * Single-shot TCP probe: resolves `true` iff a connection to `port` succeeds
+ * within `timeoutMs`, else `false` (connection error or timeout). Never rejects.
+ *
+ * When `host` is omitted the port is probed on BOTH loopback families —
+ * `127.0.0.1` (IPv4) and `::1` (IPv6) — and reported open if EITHER answers.
+ * This matters because `server.listen(port, …)` (below) passes no host, so Node
+ * binds dual-stack on `::` (all interfaces, both families). A single `localhost`
+ * probe resolves to only one of `::1`/`127.0.0.1` on a given host, so an orphan
+ * holding the port on the *other* family would be invisible — leaving the
+ * startup/EADDRINUSE reclaim path blind to a port that `listen` will still
+ * reject. Probing both families keeps every "is the port bound" check in
+ * agreement with what `listen` actually contends for. Pass an explicit `host`
+ * to probe only that address.
+ *
+ * Shared by {@link waitForPort} (wait until open), {@link waitForPortFree} (wait
+ * until closed) and the startup/EADDRINUSE reclaim path so all three agree on
+ * exactly what "the port is bound" means.
+ */
+export declare function isPortOpen(port: number, host?: string, timeoutMs?: number): Promise<boolean>;
 /** Bounded auto-respawn policy for the frontend dev server. */
 export interface FrontendRespawnPolicy {
     /** Max restarts allowed within `windowMs` before giving up (prevents hot loops). */
@@ -109,5 +129,153 @@ export declare function shouldCreditFrontendReady(child: {
     exitCode: number | null;
     signalCode: NodeJS.Signals | null;
 } | null, current: unknown): boolean;
+/** Outcome of {@link reclaimPort}. */
+export interface ReclaimResult {
+    /** Whether the port was bound when reclaim started. */
+    wasOpen: boolean;
+    /** Whether the port is free once reclaim finishes (true when it was never open). */
+    reclaimed: boolean;
+    /** Listener PIDs discovered (and signalled). Empty when the port was free, or no owner PID was found. */
+    pids: number[];
+}
+/** Injectable seams for {@link reclaimPort} (real implementations by default). */
+export interface ReclaimPortDeps {
+    /** True iff the port is currently bound. */
+    probe: (port: number) => Promise<boolean>;
+    /** PIDs of the listener(s) holding the port. */
+    listPids: (port: number) => number[];
+    /** Terminate a listener PID's tree (POSIX group kill / Windows taskkill). */
+    killTree: (pid: number, signal: NodeJS.Signals) => void;
+    /** Wait (bounded) for the port to be released. */
+    waitFree: (port: number, timeoutMs?: number) => Promise<void>;
+}
+/**
+ * Free a port left bound by a crashed / SIGKILL'd predecessor so a fresh dev
+ * server can bind the `:3000` front door — or spawn its `--strictPort` frontend
+ * on `:3100` — instead of colliding on it and crashing.
+ *
+ * No-op when the port is already free. Otherwise it discovers the listener PID(s)
+ * ({@link findListenerPids}, an `lsof`/`netstat` probe — the same fuser-style
+ * mechanism `cleanup` uses), SIGTERMs each ({@link killListenerTree}, which
+ * reuses the frontend process-group kill), waits (bounded) for release
+ * ({@link waitForPortFree}), then escalates to SIGKILL if the port is still held.
+ * This deliberately mirrors the respawn path (process-group kill + port-free
+ * wait) rather than inventing a new teardown mechanism.
+ *
+ * The caller is responsible for NOT reclaiming a *healthy peer* dev server — the
+ * singleton guard ({@link evaluateSingleton}) runs first and bows out when a live
+ * peer owns the front door, so anything still holding these ports here is an
+ * orphan. Dependencies are injected for tests; returns what it did for
+ * logging/assertions. Best-effort: never throws.
+ *
+ * Probe contract: the default `probe` is {@link isPortOpen} with no host, which
+ * checks BOTH `127.0.0.1` and `::1`. `server.listen` binds dual-stack on `::`,
+ * so an orphan holding the port on either loopback family is detected (and thus
+ * reclaimed) — a single-family `localhost` probe could miss it and no-op.
+ */
+export declare function reclaimPort(port: number, deps?: Partial<ReclaimPortDeps>): Promise<ReclaimResult>;
+/**
+ * Build the console message for a startup reclaim of a port that was in use,
+ * distinguishing the three meaningfully different outcomes so the operator knows
+ * what (if anything) to do next:
+ *  - reclaimed → we freed it; startup continues.
+ *  - not reclaimed but owner PID(s) known → tell the operator exactly which
+ *    process(es) to stop and retry.
+ *  - not reclaimed and no owner PID found → nothing to point at (lsof/netstat
+ *    found no listener), so surface the generic "in use" message.
+ * `subject` describes what was reclaimed (e.g. 'a stale/orphaned listener'). Pure.
+ */
+export declare function reclaimMessage(port: number, result: ReclaimResult, subject: string): string;
+/** Bounded retry policy for binding the `:3000` front door under EADDRINUSE. */
+export interface PortBindRetryPolicy {
+    /** Total bind attempts tolerated before giving up (exit non-zero). */
+    maxAttempts: number;
+    /** Base backoff (ms); scaled by the attempt number between retries. */
+    backoffMs: number;
+}
+/** Default front-door bind retry budget: 3 attempts, 250ms→750ms linear backoff. */
+export declare const DEFAULT_PORT_BIND_RETRY_POLICY: PortBindRetryPolicy;
+/**
+ * Decide whether an EADDRINUSE on the `:3000` front door should trigger another
+ * reclaim-and-rebind attempt. `attempt` is the number of failures so far
+ * (1-based). Returns `retry: false` once the budget is exhausted so the caller
+ * exits non-zero with a clear message rather than looping forever. Pure.
+ */
+export declare function evaluatePortBindRetry(attempt: number, policy?: PortBindRetryPolicy): {
+    retry: boolean;
+    delayMs: number;
+};
+/** Injectable seams for {@link createBindRetryController} (real implementations wired at the call site). */
+export interface BindRetryDeps {
+    /** Reclaim the contended port; its result drives the operator message. */
+    reclaim: (port: number) => Promise<ReclaimResult>;
+    /** Re-attempt the bind (`server.listen(port, onListening)` in prod). */
+    relisten: () => void;
+    /** Schedule the next attempt after a backoff (`setTimeout` in prod). */
+    scheduleRetry: (fn: () => void, delayMs: number) => void;
+    /** Called once the attempt budget is exhausted (`process.exit(1)` in prod). */
+    onExhausted: () => void;
+    /** Warning/error sink (`console.error` in prod). */
+    warn: (msg: string) => void;
+}
+/**
+ * Build the `:3000` front-door EADDRINUSE bind-retry handler. Extracted from the
+ * `server.on('error')` closure so the retry *wiring* — the 1-based attempt
+ * counter, the bounded {@link evaluatePortBindRetry} decision, reclaim-result
+ * routing, and retry scheduling — is unit-testable without a real socket.
+ *
+ * Returns a function to invoke on each EADDRINUSE. Per invocation it:
+ *  - increments the attempt counter and consults {@link evaluatePortBindRetry};
+ *  - on exhaustion: warns with an actionable message and calls `onExhausted`
+ *    (no further retry is scheduled);
+ *  - otherwise: warns it is retrying, then (async) reclaims the port and — when
+ *    reclaim did NOT free it — surfaces the {@link reclaimMessage} naming the
+ *    holding pid(s) so the operator isn't left with only the generic banner,
+ *    then schedules the next `relisten` after the decided backoff.
+ * Never throws.
+ */
+export declare function createBindRetryController(port: number, deps: BindRetryDeps, policy?: PortBindRetryPolicy): () => void;
+/** Persisted identity of the dev server that owns a given front-door port. */
+export interface DevServerPidRecord {
+    /** The supervisor process's own pid. */
+    pid: number;
+    /** The supervisor's parent pid — the stable `tsx watch` watcher across reloads. */
+    ppid: number;
+    /** The front-door port this record guards. */
+    port: number;
+}
+/** Parse a pidfile body into a {@link DevServerPidRecord}; `null` if absent/corrupt/incomplete. */
+export declare function parsePidRecord(text: string): DevServerPidRecord | null;
+/** True iff a signal can be delivered to `pid` (exists). `EPERM` (exists, not ours) counts as alive. */
+export declare function isPidAlive(pid: number, kill?: (pid: number, signal: number) => void): boolean;
+/** Result of {@link evaluateSingleton}: proceed with startup, or exit cleanly (a live peer owns the port). */
+export type SingletonDecision = {
+    action: 'proceed';
+} | {
+    action: 'exit';
+    reason: string;
+};
+/**
+ * Decide whether a *new* dev-server invocation should start, or bow out because
+ * another supervisor already owns `port`. This is the singleton guard that stops
+ * the "two fighting supervisors" restart loop — a second `npm run dev` racing the
+ * first on `:3000`/`:3100` — WITHOUT breaking `tsx watch`'s own restart of the
+ * *same* supervisor on a file change.
+ *
+ * - **No / corrupt pidfile** → proceed (first start; startup reclaim covers any orphan socket).
+ * - **Same pid** → proceed (defensive; the record is our own).
+ * - **Same parent (`ppid`)** → proceed. `tsx watch` is the stable parent across
+ *   reloads, so a matching parent means the watcher is relaunching OUR OWN script
+ *   — not a competitor. A second `npm run dev` runs under a *different* watcher,
+ *   so it never matches here. This carve-out is what preserves hot reload.
+ * - **Different, still-live owner actually holding the port** → exit cleanly with
+ *   a clear message (do not spawn a competing supervisor).
+ * - **Otherwise** (recorded owner is dead → stale pidfile, or the port is free)
+ *   → proceed; startup reclaim frees any orphaned socket.
+ */
+export declare function evaluateSingleton(existing: DevServerPidRecord | null, self: {
+    pid: number;
+    ppid: number;
+}, portInUse: boolean, isAlive: (pid: number) => boolean): SingletonDecision;
 export declare function startDevServer(options: DevServerOptions): Promise<void>;
 //# sourceMappingURL=dev-server.d.ts.map

package/dist/scripts/dev-server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dev-server.d.ts","sourceRoot":"","sources":["../../src/scripts/dev-server.ts"],"names":[],"mappings":"AAoCA,eAAO,MAAM,iBAAiB,QAAiD,CAAC;AAEhF;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAE3D;AAED,sFAAsF;AACtF,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,OAAO,GAAG,SAAS,CAAC;CAClC;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,OAAO,GAAG,mBAAmB,CAKvF;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAE/E;AAED,MAAM,WAAW,gBAAgB;IAC/B,2CAA2C;IAC3C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,oCAAoC;IACpC,WAAW,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,8DAA8D;IAC9D,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAmCD,+DAA+D;AAC/D,MAAM,WAAW,qBAAqB;IACpC,oFAAoF;IACpF,WAAW,EAAE,MAAM,CAAC;IACpB,2DAA2D;IAC3D,QAAQ,EAAE,MAAM,CAAC;IACjB,yEAAyE;IACzE,SAAS,EAAE,MAAM,CAAC;IAClB,oDAAoD;IACpD,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,uFAAuF;AACvF,eAAO,MAAM,+BAA+B,EAAE,qBAK7C,CAAC;AAEF,kDAAkD;AAClD,MAAM,WAAW,eAAe;IAC9B,oDAAoD;IACpD,OAAO,EAAE,OAAO,CAAC;IACjB,mEAAmE;IACnE,OAAO,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,uBAAuB,CACrC,cAAc,EAAE,MAAM,EAAE,EACxB,GAAG,EAAE,MAAM,EACX,MAAM,GAAE,qBAAuD,GAC9D,eAAe,CAOjB;AAED;;;;;;GAMG;AACH,wBAAsB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,SAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAenF;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,yBAAyB,CACvC,KAAK,EAAE;IAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC,OAAO,GAAG,IAAI,CAAA;CAAE,GAAG,IAAI,EAC5E,OAAO,EAAE,OAAO,GACf,OAAO,CAOT;AAED,wBAAsB,cAAc,CAAC,OAAO,EAAE,gBAAgB,iBAya7D"}
+{"version":3,"file":"dev-server.d.ts","sourceRoot":"","sources":["../../src/scripts/dev-server.ts"],"names":[],"mappings":"AAqCA,eAAO,MAAM,iBAAiB,QAAiD,CAAC;AAEhF;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAE3D;AAED,sFAAsF;AACtF,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,OAAO,GAAG,SAAS,CAAC;CAClC;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,OAAO,GAAG,mBAAmB,CAKvF;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAE/E;AAED,MAAM,WAAW,gBAAgB;IAC/B,2CAA2C;IAC3C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,oCAAoC;IACpC,WAAW,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,8DAA8D;IAC9D,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAiBD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,EAAE,SAAS,SAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAa/F;AAYD,+DAA+D;AAC/D,MAAM,WAAW,qBAAqB;IACpC,oFAAoF;IACpF,WAAW,EAAE,MAAM,CAAC;IACpB,2DAA2D;IAC3D,QAAQ,EAAE,MAAM,CAAC;IACjB,yEAAyE;IACzE,SAAS,EAAE,MAAM,CAAC;IAClB,oDAAoD;IACpD,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,uFAAuF;AACvF,eAAO,MAAM,+BAA+B,EAAE,qBAK7C,CAAC;AAEF,kDAAkD;AAClD,MAAM,WAAW,eAAe;IAC9B,oDAAoD;IACpD,OAAO,EAAE,OAAO,CAAC;IACjB,mEAAmE;IACnE,OAAO,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,uBAAuB,CACrC,cAAc,EAAE,MAAM,EAAE,EACxB,GAAG,EAAE,MAAM,EACX,MAAM,GAAE,qBAAuD,GAC9D,eAAe,CAOjB;AAED;;;;;;GAMG;AACH,wBAAsB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,SAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAOnF;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,yBAAyB,CACvC,KAAK,EAAE;IAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC,OAAO,GAAG,IAAI,CAAA;CAAE,GAAG,IAAI,EAC5E,OAAO,EAAE,OAAO,GACf,OAAO,CAOT;AAID,sCAAsC;AACtC,MAAM,WAAW,aAAa;IAC5B,uDAAuD;IACvD,OAAO,EAAE,OAAO,CAAC;IACjB,oFAAoF;IACpF,SAAS,EAAE,OAAO,CAAC;IACnB,yGAAyG;IACzG,IAAI,EAAE,MAAM,EAAE,CAAC;CAChB;AAED,kFAAkF;AAClF,MAAM,WAAW,eAAe;IAC9B,4CAA4C;IAC5C,KAAK,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IAC1C,gDAAgD;IAChD,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,EAAE,CAAC;IACrC,6EAA6E;IAC7E,QAAQ,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,OAAO,KAAK,IAAI,CAAC;IACxD,kDAAkD;IAClD,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CAC/D;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAsB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,GAAE,OAAO,CAAC,eAAe,CAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CAwB3G;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAW3F;AAED,gFAAgF;AAChF,MAAM,WAAW,mBAAmB;IAClC,sEAAsE;IACtE,WAAW,EAAE,MAAM,CAAC;IACpB,uEAAuE;IACvE,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,oFAAoF;AACpF,eAAO,MAAM,8BAA8B,EAAE,mBAG5C,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,MAAM,EACf,MAAM,GAAE,mBAAoD,GAC3D;IAAE,KAAK,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAGrC;AAED,4GAA4G;AAC5G,MAAM,WAAW,aAAa;IAC5B,0EAA0E;IAC1E,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,aAAa,CAAC,CAAC;IAClD,wEAAwE;IACxE,QAAQ,EAAE,MAAM,IAAI,CAAC;IACrB,wEAAwE;IACxE,aAAa,EAAE,CAAC,EAAE,EAAE,MAAM,IAAI,EAAE,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IACzD,+EAA+E;IAC/E,WAAW,EAAE,MAAM,IAAI,CAAC;IACxB,oDAAoD;IACpD,IAAI,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;CAC7B;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,yBAAyB,CACvC,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,aAAa,EACnB,MAAM,GAAE,mBAAoD,GAC3D,MAAM,IAAI,CAwBZ;AAID,8EAA8E;AAC9E,MAAM,WAAW,kBAAkB;IACjC,wCAAwC;IACxC,GAAG,EAAE,MAAM,CAAC;IACZ,mFAAmF;IACnF,IAAI,EAAE,MAAM,CAAC;IACb,8CAA8C;IAC9C,IAAI,EAAE,MAAM,CAAC;CACd;AAED,mGAAmG;AACnG,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,kBAAkB,GAAG,IAAI,CAUtE;AAED,wGAAwG;AACxG,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,GAAE,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,KAAK,IAAmC,GAAG,OAAO,CAQ3H;AAED,8GAA8G;AAC9G,MAAM,MAAM,iBAAiB,GAAG;IAAE,MAAM,EAAE,SAAS,CAAA;CAAE,GAAG;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAE3F;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,kBAAkB,GAAG,IAAI,EACnC,IAAI,EAAE;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,EACnC,SAAS,EAAE,OAAO,EAClB,OAAO,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,GAChC,iBAAiB,CASnB;AAED,wBAAsB,cAAc,CAAC,OAAO,EAAE,gBAAgB,iBAsiB7D"}