@yawlabs/postgres-mcp 0.11.1 → 0.12.0

package/CHANGELOG.md

@@ -7,6 +7,95 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.12.0] - 2026-08-23
+
+### Added
+
+- **`pg_index_advisor`, an index RECOMMENDATION tool.** The server already had
+  every input -- HypoPG for hypothetical indexes, `pg_stat_statements` via
+  `pg_top_queries`, and `pg_seq_scan_tables` -- and lacked only the search layer.
+  Candidates are costed by creating hypothetical indexes, re-running EXPLAIN, and
+  keeping what actually lowers cost, under a caller-set bound on candidates and
+  EXPLAIN round trips. Hypothetical indexes are session-scoped, so `hypopg_reset()`
+  runs in a teardown that fires even on error; leaking them would poison every
+  later plan in the session.
+
+  Encoded correctness note: PostgreSQL 18's skip scan means a multi-column btree
+  with an unconstrained LEADING column can now be used, so the classic "leading
+  column never filtered = dead index" heuristic is wrong on PG18+. That reasoning
+  is version-gated.
+
+- **Structured tool output.** Every tool now declares an `outputSchema` and
+  returns `structuredContent` alongside the existing serialized text block.
+  Tools that return a bare array wrap it as `{ rows: [...] }`, because
+  `structuredContent` must be a JSON object; the `content` block is unchanged, so
+  nothing that reads it today breaks. Version-gated fields are modelled as
+  OPTIONAL rather than nullable -- absence is a deliberate signal in this codebase
+  and a nullable schema would erase the distinction.
+
+- **Opt-in audit logging of agent SQL** via `POSTGRES_AUDIT_LOG` /
+  `POSTGRES_AUDIT_LOG_FILE` / `POSTGRES_AUDIT_REDACT`, off by default. One JSON
+  line per statement: timestamp, tool, SQL, parameter COUNT, duration, rows, and
+  ok/SQLSTATE. Parameter VALUES are never logged -- they routinely carry PII and
+  credentials. A redacting mode logs only the leading keyword plus a hash for
+  operators who want the trail without the content. An unopenable sink fails
+  LOUDLY at startup rather than degrading to no trail, since an audit control that
+  quietly disables itself is worse than none.
+
+- **PostgreSQL 19 forward-compatibility.** PG19 renames
+  `pg_stat_subscription_stats.sync_error_count` to `sync_table_error_count` and
+  wait event type `BUFFERPIN` to `BUFFER`. Wait-event values are asserted to pass
+  through untouched, so a future filter on the old literal -- which would silently
+  match nothing on PG19 -- cannot be added without failing a test.
+
+### Changed
+
+- **Dual-era MCP protocol support.** The server was legacy-only: it pinned SDK
+  v1, which tops out at protocol revision 2025-11-25, and the current revision's
+  compatibility matrix states that a modern client talking to a legacy server
+  FAILS. It now serves both eras via SDK v2's `serveStdio`. The existing
+  process-level tests still drive a real `initialize` handshake against the
+  emitted bundle, which is what proves the legacy path still works.
+
+### Fixed
+
+- **`release.sh` could report a failed release as a success.** The status lived
+  in a value a caller could easily discard, and a pipeline returns its LAST
+  command's status -- so a release that died at the push step read as exit 0. The
+  failure banner is now the final thing written, on both streams, naming the step
+  and its remedy. Re-entry is also guarded: a local tag that does not match the
+  commit being released now fails loudly instead of building a GitHub release
+  from an orphaned tag.
+
+- **`wsl-test-matrix.sh` tested against stale dependencies.** It ran `npm ci`
+  only when `node_modules` was ABSENT, so a branch that changed a dependency was
+  silently tested against the previous branch's tree. It reinstalls on a
+  lockfile-hash change, and a failing install aborts instead of proceeding. This
+  produced a red matrix on all three majors during this very change set.
+
+- **The oam sandbox allowlist dropped the new audit variables.** oam removes an
+  undeclared variable rather than denying it, so `POSTGRES_MCP_SANDBOX=1` would
+  have silently disabled the audit trail. Caught by the bundle-scanning test
+  added in 0.11.0. Also documented that the sandbox denies the filesystem, so a
+  FILE audit sink cannot open under it -- use the stderr sink there.
+
+- **Integration tests called handlers with arguments no MCP client could send.**
+  Several call sites passed a `limit` above the declared schema maximum; direct
+  handler calls bypass Zod, so they silently worked and a cap regression would
+  not have been caught. Bounds are now respected, and a schema-level test pins
+  the cap.
+
+
+## [0.11.2] - 2026-08-23
+
+### Fixed
+- **The launcher no longer dies with a raw stack trace when `spawn` fails.** Node throws synchronously rather than emitting `error` for some unexecutable targets — notably a `.cmd`/`.bat` on Windows — and the `error` listener is registered *after* the `spawn` call, so it could never observe that throw. Both failure modes now route through one handler.
+- **Windows `PATH` discovery accepts `oam.exe` only**, instead of walking every `PATHEXT` entry and returning an `oam.cmd` Node cannot execute. A skipped shim is still **named** in the diagnostic, so an npm-style install no longer reports as "no oam binary was found".
+- **A failing in-process fallback no longer escapes as an unhandled rejection.** `void runInProcess()` discarded the promise, replacing the launcher's own diagnostic with a raw stack trace.
+- **Diagnostics that precede `process.exit` are written synchronously.** stderr is async for TTYs and pipes on Windows, so the exit could truncate them. They route through one helper that also handles short writes and macOS `EAGAIN` on a non-blocking piped stderr.
+- Removed a literal backspace byte (`U+0008`) from the runtime-discovery comment, which made git treat the file as binary so its diff could not be reviewed.
+- **An oam that cannot be *run* is no longer reported as an *outdated* one.** The version probe returns null for several distinct causes — not executable, wrong architecture, a shim Node refuses, deleted since the stat, unparseable `--version` output — and every one produced "older than oam 0.9.0 … run `oam self-update`", pointing at the single cause it definitely was not. The two cases now carry separate wording and remedies, and the outdated message reports the version actually detected.
+
 ## [0.11.1] - 2026-08-23
 
 ### Fixed

package/README.md

@@ -190,6 +190,7 @@ The bigger leverage is multi-tool reasoning. A few real workflows:
 | `pg_list_extensions` | List installed extensions (pgvector, postgis, pg_stat_statements, etc.) with versions. |
 | `pg_search_columns` | Find columns by name pattern across all user schemas. Case-insensitive, supports SQL LIKE wildcards. |
 | `pg_explain` | `EXPLAIN` or `EXPLAIN ANALYZE` for a SQL statement. Text or JSON output. Planner options: `buffers` (on by default with `analyze`), `settings`, `verbose`, `wal`, `costs`, `timing`, plus `generic_plan` (PG16+, plan a parameterized query with no values) and `memory` / `serialize` (PG17+). Optional `hypothetical_indexes` (requires the [HypoPG](https://github.com/HypoPG/hypopg) extension) lets you ask "what would the plan be with these indexes?" without creating them on disk. |
+| `pg_index_advisor` | Recommend indexes for a workload and prove each one pays for itself first. Takes `statements` you pass or the top N from `pg_stat_statements`, harvests candidate columns from what the **planner** reports as filters / join keys / sort keys (no SQL parser - every token is intersected with the real `pg_attribute` column list), then costs each candidate with [HypoPG](https://github.com/HypoPG/hypopg) hypothetical indexes and keeps only what measurably lowers estimated cost. Greedy and bounded via `max_candidates` / `max_explains`, so a big workload cannot run away; `budget_exhausted` flags a truncated search. Returns the `CREATE INDEX` (plus a `CONCURRENTLY` form), cost before/after, which statements each index helps, and the estimated size. **PG18-aware:** PG18 added B-tree skip scan, so a multi-column index whose leading column is never filtered is no longer useless - that classic prune is gated on the server version rather than applied blindly. Requires HypoPG; indexes are session-scoped and reset on every exit path. |
 | `pg_health` | Server version, database size, connections against `max_connections`, active queries with wait events and transaction age, `pg_stat_database` rollup (deadlocks, temp files, cache hit ratio), table count. |
 | `pg_top_queries` | Top N queries by total/mean execution time. Requires the `pg_stat_statements` extension. Returns `stats_reset` (from `pg_stat_statements_info`, a different clock from the other stats tools) and `dealloc` on extension 1.9+ - a non-zero `dealloc` means entries were evicted past `pg_stat_statements.max`, so the ranking is drawn from an incomplete population. |
 | `pg_seq_scan_tables` | Tables with heavy sequential scans - missing-index candidates. Returns the `stats_reset` window alongside the rows, since the counters mean nothing without it. `last_seq_scan` / `last_idx_scan` on PG16+. |

package/bin/postgres-mcp.mjs

@@ -97,13 +97,16 @@ function findOam() {
 
   // 2. PATH. Resolved manually rather than by spawning `which`/`where`, which
   //    would cost a subprocess on every launch just to decide whether to spawn.
-  const pathExt = isWin ? (process.env.PATHEXT ?? ".EXE").split(";").filter(Boolean) : [""];
+  // Windows: `.exe` ONLY -- deliberately narrower than PATHEXT. Node refuses to
+  // run a .cmd/.bat through execFile/spawn without `shell: true` (EINVAL, and
+  // for spawn it throws SYNCHRONOUSLY rather than emitting 'error'), so walking
+  // the full PATHEXT list would hand back a path this launcher cannot execute.
+  // Discovery has to agree with execution. A skipped shim is still reported --
+  // see findOamShim.
   for (const dir of (process.env.PATH ?? "").split(delimiter)) {
     if (!dir) continue;
-    for (const ext of isWin ? pathExt : [""]) {
-      const candidate = join(dir, isWin ? `oam${ext.toLowerCase()}` : "oam");
-      if (existsSync(candidate)) return candidate;
-    }
+    const candidate = join(dir, exe);
+    if (existsSync(candidate)) return candidate;
   }
 
   // 3. The per-user locations oamjs.org's installers write to. Checked because
@@ -187,14 +190,74 @@ function sandboxFlags() {
   // getApplicationName() in src/api.ts; PGAPPNAME is pg's own env fallback for
   // the same setting (connection-parameters.js: val('application_name', config,
   // 'PGAPPNAME')), so omitting it would drop a name set the driver's way.
-  const env = ["ALLOW_WRITES","DATABASE_URL","NODE_PG_FORCE_NATIVE","PGAPPNAME","PGCONNECT_TIMEOUT","PGSSLMODE","POSTGRES_APPLICATION_NAME","POSTGRES_CONNECTION_TIMEOUT_MS","POSTGRES_MAX_ROWS","POSTGRES_POOL_MAX","POSTGRES_SSL_REJECT_UNAUTHORIZED","POSTGRES_STATEMENT_TIMEOUT_MS","USER","USERNAME"];
+  // POSTGRES_AUDIT_LOG_FILE is granted as a VARIABLE here, but the sandbox
+  // still denies the filesystem, so the file sink cannot actually open its
+  // target under POSTGRES_MCP_SANDBOX=1. The audit module fails loudly on an
+  // unopenable sink rather than silently dropping the trail, so the combination
+  // refuses to start -- which is the correct outcome (an audit control that
+  // quietly disables itself is worse than none), but it is a surprising one to
+  // hit at runtime. Use the stderr sink under the sandbox.
+  const env = ["ALLOW_WRITES","DATABASE_URL","NODE_PG_FORCE_NATIVE","PGAPPNAME","PGCONNECT_TIMEOUT","PGSSLMODE","POSTGRES_APPLICATION_NAME","POSTGRES_AUDIT_LOG","POSTGRES_AUDIT_LOG_FILE","POSTGRES_AUDIT_REDACT","POSTGRES_CONNECTION_TIMEOUT_MS","POSTGRES_MAX_ROWS","POSTGRES_POOL_MAX","POSTGRES_SSL_REJECT_UNAUTHORIZED","POSTGRES_STATEMENT_TIMEOUT_MS","USER","USERNAME"];
 
   const flags = ["--permission", netFlag, `--allow-env=${env.join(",")}`];
   return flags;
 }
 
+/**
+ * Write a diagnostic to stderr synchronously, so a following process.exit
+ * cannot truncate it.
+ *
+ * Not a bare writeSync: that call can short-write (it returns a byte count) and
+ * on macOS it can throw EAGAIN, because Node makes a piped stderr non-blocking
+ * there rather than blocking the write. Loop over the remaining bytes, and if
+ * stderr turns out to be unusable give up quietly -- failing to print a
+ * diagnostic is not worth crashing a stdio server over.
+ */
+async function errSync(message) {
+  const { writeSync } = await import("node:fs");
+  const buf = Buffer.from(message);
+  let off = 0;
+  for (let attempts = 0; off < buf.length && attempts < 1000; attempts++) {
+    try {
+      off += writeSync(2, buf, off, buf.length - off);
+    } catch (err) {
+      if (err?.code !== "EAGAIN") return;
+      // Pipe is full and the reader has not drained yet -- retry.
+    }
+  }
+}
+
+/**
+ * An oam-named .cmd/.bat on PATH: a real install in a shape this launcher
+ * cannot spawn. Reported rather than ignored, because "no oam binary was found"
+ * reads as "install oam" -- the one thing that will not help. Windows only;
+ * there is no such shim concept on POSIX.
+ */
+function findOamShim() {
+  if (!isWin) return null;
+  for (const dir of (process.env.PATH ?? "").split(delimiter)) {
+    if (!dir) continue;
+    for (const ext of [".cmd", ".bat"]) {
+      const candidate = join(dir, `oam${ext}`);
+      if (existsSync(candidate)) return candidate;
+    }
+  }
+  return null;
+}
+
 /** Run the server in THIS process. The zero-overhead fallback. */
 async function runInProcess() {
+  // A server may gate its bootstrap on being the process ENTRY POINT --
+  // `import.meta.url === pathToFileURL(process.argv[1]).href` -- so that its own
+  // test file can import the module for unit tests without connecting a stdio
+  // transport. Importing the server here would leave argv[1] pointing at THIS
+  // launcher, the guard would read false, and the server would load but never
+  // serve: the MCP handshake just hangs.
+  //
+  // Point argv[1] at the server first, so the in-process path is
+  // indistinguishable from having executed the file directly. The spawn path
+  // needs no equivalent -- there argv[1] is already the server.
+  process.argv[1] = SERVER_ENTRY;
   await import(SERVER_URL.href);
 }
 
@@ -204,8 +267,21 @@ if (mode === "node") {
   await runInProcess();
 } else {
   const oam = findOam();
+  // Read the version ONCE, and only when discovery found something: the
+  // gate below has to tell "too old" apart from "could not be read at all",
+  // and re-probing inside the branch would cost a second subprocess.
+  const found = oam ? oamVersion(oam) : null;
 
   if (!oam) {
+    // An oam-named .cmd/.bat on PATH is a real install in a shape this
+    // launcher cannot spawn. Naming it turns "no oam binary was found" --
+    // which reads as "install oam", the one thing that will not help --
+    // into something the user can act on.
+    const oamShim = findOamShim();
+    const shimNote = oamShim
+      ? `Found ${oamShim}, but Node cannot execute a .cmd/.bat directly.\n` +
+        "Install the native oam binary, or point OAM_BIN at one.\n"
+      : "";
     if (mode === "oam") {
       // Explicitly demanded, so this is a real misconfiguration -- do not
       // silently do something else. writeSync because stderr is async for
@@ -213,112 +289,154 @@ if (mode === "node") {
       const { writeSync } = await import("node:fs");
       writeSync(
         2,
-        "postgres-mcp: POSTGRES_MCP_RUNTIME=oam but no oam binary was found.\n" +
+        "postgres-mcp: POSTGRES_MCP_RUNTIME=oam but no runnable oam binary was found.\n" + shimNote +
           "Install from https://oamjs.org, set OAM_BIN=/path/to/oam, or use POSTGRES_MCP_RUNTIME=node.\n",
       );
       process.exit(1);
     }
+    // auto: falling back is correct, but silence is how someone never learns
+    // their oam install is a shape this launcher skips.
+    if (oamShim) await errSync(`postgres-mcp: ${shimNote}Using Node instead.\n`);
     await runInProcess();
-  } else if (!atLeast(oamVersion(oam), OAM_MIN)) {
-    // Discovery itself stays stat-only; this is the first subprocess, and it
-    // runs only once we have already decided to spawn oam anyway. Measured 26ms
-    // median (n=12, windows-arm64), paid once per MCP session.
+  } else if (!atLeast(found, OAM_MIN)) {
     const min = OAM_MIN.join(".");
+    // Two different causes reach this branch and they need different
+    // remedies. `found === null` is NOT "old": oamVersion returns null when
+    // the binary could not be run at all (not executable, wrong arch, a
+    // .cmd/.bat Node refuses, deleted between the stat and the probe) or
+    // when its --version output did not parse. Telling that user to
+    // `oam self-update` sends them after the one cause it definitely is not.
+    const detail = found
+      ? `${oam} is oam ${found.join(".")}, older than ${min}`
+      : `${oam} could not be run, or did not report a version this launcher understands`;
+    const remedy = found
+      ? "Run \`oam self-update\`, or use POSTGRES_MCP_RUNTIME=node.\n"
+      : "Check that it is an executable oam binary for this platform, or use POSTGRES_MCP_RUNTIME=node.\n";
     if (mode === "oam") {
-      const { writeSync } = await import("node:fs");
-      writeSync(
-        2,
-        `postgres-mcp: POSTGRES_MCP_RUNTIME=oam but ${oam} is older than oam ${min}.\n` +
-          `Run \`oam self-update\`, or use POSTGRES_MCP_RUNTIME=node.\n`,
-      );
+      await errSync(`postgres-mcp: POSTGRES_MCP_RUNTIME=oam but ${detail}.\n${remedy}`);
       process.exit(1);
     }
-    // auto: an old oam is a reason to prefer Node, not to fail. Say so, because
-    // a silent downgrade is how someone keeps running an oam they meant to
-    // update. stderr is safe -- MCP frames travel on stdout.
-    process.stderr.write(`postgres-mcp: oam at ${oam} is older than ${min}; using Node instead.\n`);
+    // auto: neither cause is worth failing over -- prefer Node. Say so,
+    // because a silent downgrade is how someone keeps running an oam they
+    // meant to update, or never learns their oam is unexecutable.
+    await errSync(`postgres-mcp: ${detail}; using Node instead.\n`);
     await runInProcess();
   } else {
     // `--` separates oam's own flags from the script's argv. Everything after
     // it lands in process.argv for the server, so `postgres-mcp version` and
     // any host-supplied flags survive the hop unchanged.
-    const child = spawn(oam, [...sandboxFlags(), "run", SERVER_ENTRY, "--", ...process.argv.slice(2)], {
-      // inherit keeps the SAME fds, so MCP's newline-delimited JSON framing on
-      // stdin/stdout is untouched and the host's stdin-close still reaches the
-      // server's shutdown path.
-      stdio: "inherit",
-      env: process.env,
-      windowsHide: true,
-    });
-
-    // If oam cannot be executed at all (deleted between the stat and the
-    // spawn, wrong arch, permission), fall back rather than failing the whole
-    // server. `spawned` guards against falling back AFTER the child has begun
-    // running, which would double-start the server.
-    let spawned = false;
-    child.on("spawn", () => {
-      spawned = true;
-    });
-    child.on("error", (err) => {
-      if (spawned) return;
+    // Every "oam could not be executed" outcome lands here: the synchronous
+    // throw from spawn() and the async 'error' event mean the same thing and
+    // must degrade the same way, so the handling lives in one place.
+    // errSync rather than process.stderr.write because stderr is async for
+    // TTYs and pipes on Windows and the process.exit below truncates pending
+    // writes.
+    const launchFailed = async (err) => {
       if (mode === "oam") {
-        process.stderr.write(`postgres-mcp: failed to launch oam (${err.message})\n`);
+        await errSync(`postgres-mcp: failed to launch oam (${err?.message ?? err})\n`);
         process.exit(1);
       }
-      void runInProcess();
-    });
+      await runInProcess();
+    };
+
+    // ONE reporter shared by both launchFailed call sites, so the sync-throw
+    // path and the 'error'-event path cannot drift apart. Either can reject:
+    // runInProcess() is a bare import() that rejects when dist/index.js is
+    // missing, and at ESM top level an unhandled rejection is an uncaught
+    // exception -- the exact failure this handling exists to prevent.
+    const fallbackFailed = (e) => {
+      process.stderr.write(`postgres-mcp: fallback to Node failed (${e?.message ?? e})\n`);
+      process.exitCode = 1;
+    };
 
-    // Forward termination so the server's own shutdown path runs in the child
-    // rather than the child being orphaned.
-    //
-    // Registering ANY handler for these suppresses Node's default
-    // terminate-on-signal, so the parent's exit has to be arranged explicitly.
-    // `child.killed` only records that kill() was CALLED, never that the child
-    // is gone, so gating on it swallows every signal after the first and wedges
-    // the launcher with no escape hatch.
-    //
-    // Escalation is driven by a TIMER, not by counting signals. Counting is
-    // ambiguous: a supervisor routinely sends SIGINT then SIGTERM milliseconds
-    // apart, and a terminal Ctrl-C reaches the whole process group, so reading
-    // "a second signal" as impatience hard-kills a child that is already
-    // shutting down cleanly. A timer makes the count irrelevant -- ONE press is
-    // enough, and a wedged child dies on schedule. setTimeout is monotonic, so
-    // a wall-clock step cannot mis-gate the window either.
-    //
-    // POSIX vs Windows, and why we do NOT forward on Windows.
-    // On POSIX child.kill(sig) delivers a real, catchable signal, so forwarding
-    // is what lets the child run its shutdown. On Windows there are no POSIX
-    // signals: child.kill IGNORES the name and calls TerminateProcess -- an
-    // immediate hard kill (verified: a child with a SIGTERM handler never runs
-    // it and dies with code=null, signal=SIGTERM). Forwarding there ABORTS the
-    // graceful shutdown the console's own Ctrl-C just started, skipping the
-    // child's process.on("exit") cleanup. The console has already notified the
-    // child, so on Windows the timer below is the only kill we issue.
-    const ESCALATE_AFTER_MS = 2000;
-    let escalation = null;
-    for (const sig of ["SIGINT", "SIGTERM"]) {
-      process.on(sig, () => {
-        // No try/catch: kill() on an already-exited child returns false, it does
-        // not throw. It throws only for a signal the platform does not know,
-        // which SIGINT/SIGTERM/SIGKILL never are.
-        if (!isWin) child.kill(sig);
-        if (escalation) return; // already counting down; further signals are noise
-        escalation = setTimeout(() => {
-          // Still here after its grace window. Stop waiting on it.
-          child.kill("SIGKILL");
-          process.exit(128 + (constants.signals[sig] ?? 15));
-        }, ESCALATE_AFTER_MS);
+    let child = null;
+    try {
+      child = spawn(oam, [...sandboxFlags(), "run", SERVER_ENTRY, "--", ...process.argv.slice(2)], {
+        // inherit keeps the SAME fds, so MCP's newline-delimited JSON framing on
+        // stdin/stdout is untouched and the host's stdin-close still reaches the
+        // server's shutdown path.
+        stdio: "inherit",
+        env: process.env,
+        windowsHide: true,
       });
+    } catch (err) {
+      // spawn() THROWS for some failures instead of emitting 'error', and the
+      // 'error' listener is registered AFTER this call, so it can never observe
+      // one -- an uncaught throw here kills the launcher with a raw stack trace
+      // instead of falling back to Node.
+      await launchFailed(err).catch(fallbackFailed);
     }
 
-    child.on("exit", (code, signal) => {
-      if (escalation) clearTimeout(escalation);
-      // Mirror the child's fate: a signal death becomes 128+n so callers see a
-      // conventional shell exit status rather than a bare 0.
-      if (signal) {
-        process.exit(128 + (constants.signals[signal] ?? 15));
+    if (child) {
+
+      // If oam cannot be executed at all (deleted between the stat and the
+      // spawn, wrong arch, permission), fall back rather than failing the whole
+      // server. `spawned` guards against falling back AFTER the child has begun
+      // running, which would double-start the server.
+      let spawned = false;
+      child.on("spawn", () => {
+        spawned = true;
+      });
+      child.on("error", (err) => {
+        if (spawned) return;
+        // Handle the rejection instead of discarding it: a failing in-process
+        // fallback would otherwise escape as an unhandled rejection, replacing
+        // this launcher's diagnostic with a raw stack trace.
+        launchFailed(err).catch(fallbackFailed);
+      });
+
+      // Forward termination so the server's own shutdown path runs in the child
+      // rather than the child being orphaned.
+      //
+      // Registering ANY handler for these suppresses Node's default
+      // terminate-on-signal, so the parent's exit has to be arranged explicitly.
+      // `child.killed` only records that kill() was CALLED, never that the child
+      // is gone, so gating on it swallows every signal after the first and wedges
+      // the launcher with no escape hatch.
+      //
+      // Escalation is driven by a TIMER, not by counting signals. Counting is
+      // ambiguous: a supervisor routinely sends SIGINT then SIGTERM milliseconds
+      // apart, and a terminal Ctrl-C reaches the whole process group, so reading
+      // "a second signal" as impatience hard-kills a child that is already
+      // shutting down cleanly. A timer makes the count irrelevant -- ONE press is
+      // enough, and a wedged child dies on schedule. setTimeout is monotonic, so
+      // a wall-clock step cannot mis-gate the window either.
+      //
+      // POSIX vs Windows, and why we do NOT forward on Windows.
+      // On POSIX child.kill(sig) delivers a real, catchable signal, so forwarding
+      // is what lets the child run its shutdown. On Windows there are no POSIX
+      // signals: child.kill IGNORES the name and calls TerminateProcess -- an
+      // immediate hard kill (verified: a child with a SIGTERM handler never runs
+      // it and dies with code=null, signal=SIGTERM). Forwarding there ABORTS the
+      // graceful shutdown the console's own Ctrl-C just started, skipping the
+      // child's process.on("exit") cleanup. The console has already notified the
+      // child, so on Windows the timer below is the only kill we issue.
+      const ESCALATE_AFTER_MS = 2000;
+      let escalation = null;
+      for (const sig of ["SIGINT", "SIGTERM"]) {
+        process.on(sig, () => {
+          // No try/catch: kill() on an already-exited child returns false, it does
+          // not throw. It throws only for a signal the platform does not know,
+          // which SIGINT/SIGTERM/SIGKILL never are.
+          if (!isWin) child.kill(sig);
+          if (escalation) return; // already counting down; further signals are noise
+          escalation = setTimeout(() => {
+            // Still here after its grace window. Stop waiting on it.
+            child.kill("SIGKILL");
+            process.exit(128 + (constants.signals[sig] ?? 15));
+          }, ESCALATE_AFTER_MS);
+        });
       }
-      process.exit(code ?? 0);
-    });
+
+      child.on("exit", (code, signal) => {
+        if (escalation) clearTimeout(escalation);
+        // Mirror the child's fate: a signal death becomes 128+n so callers see a
+        // conventional shell exit status rather than a bare 0.
+        if (signal) {
+          process.exit(128 + (constants.signals[signal] ?? 15));
+        }
+        process.exit(code ?? 0);
+      });
+    }
   }
 }