@yawlabs/lemonsqueezy-mcp 0.14.2 → 1.0.0

package/bin/lemonsqueezy-mcp.mjs

@@ -1,665 +1,667 @@
-#!/usr/bin/env node
-/**
- * Runtime launcher for @yawlabs/lemonsqueezy-mcp.
- *
- * Prefers the newest usable oam runtime (https://oamjs.org) and falls back to
- * Node. It never serves on an oam older than the floor below.
- *
- *
- * WHY THE FALLBACK COSTS NOTHING
- * npm has already started Node to run this launcher, so falling back is a
- * plain `import()` of the server into THIS process: no extra spawn, no extra
- * startup, byte-identical to invoking dist/index.js directly. Finding the
- * candidates is stat-only, so a machine without oam never pays for a
- * subprocess.
- *
- * WHAT THE OAM PATH COSTS
- * Reaching oam through an npm `bin` means Node boots first, every oam binary
- * found is asked for its version, and then oam boots to serve -- so the
- * launcher is slower than pointing a host at oam directly. Measured on
- * npmjs-mcp (windows-arm64, n=12 medians, spawn to first MCP initialize):
- * oam 116ms, node 172ms, launcher 243ms. It exists for `npx` convenience.
- *
- * For an MCP host config, point straight at oam and skip this file:
- *   { "command": "oam", "args": ["run", "<abs>/dist/index.js"] }
- *
- * WHICH OAM
- * OAM_BIN, when set and usable, is used as given. Otherwise every oam binary
- * discovery can see -- the installed locations, then PATH -- is asked for its
- * version, and the NEWEST one at or above the floor wins; a tie keeps search
- * order. Taking the first binary found instead let a stale copy early in the
- * search order hide a current one later: with oam 0.9.0 installed in ~/.oam/bin
- * and 0.15.2 on PATH, the launcher bound to 0.9.0 because installed locations
- * are searched first.
- *
- * An OAM_BIN that does not exist, is below the floor, or will not run is named
- * on stderr and discovery carries on. It used to stop everything: a typo in
- * OAM_BIN meant Node, with no hint why.
- *
- * ALREADY RUNNING ON OAM
- * A host can resolve this package's `bin` and launch `oam run <this file>`
- * instead of `node <this file>` -- Yaw MCP does, and so does oam's sidecar
- * regression matrix. When `process.versions.oam` clears the floor, the server
- * is imported into THIS process exactly as the Node fallback is -- no
- * discovery, no `oam --version` probe, no second oam. OAM_BIN is a discovery
- * input, so it is not consulted on that path: the host has already chosen
- * which oam runs.
- *
- * LEMONSQUEEZY_MCP_SANDBOX=1 is the exception, deliberately. `--permission` is
- * a process-level flag that only a FRESH oam can apply, so a supported oam host
- * still takes the discovery path and spawns one -- skipping straight to
- * in-process there would drop the sandbox without a word, a security downgrade
- * dressed up as an optimisation.
- *
- * A host oam BELOW the floor never serves. It hands the server off to the
- * newest usable oam, or to Node found on PATH, or exits with an error when
- * there is neither.
- *
- * Any handoff from an oam host PIPES stdio rather than inheriting it. Before
- * 0.9.0 oam treated `stdio: 'inherit'` as `'pipe'`, so an inherited handoff
- * from such a host connected the child to pipes nobody reads: measured with a
- * real oam 0.8.2 host, the MCP handshake never answered. Piping the streams
- * explicitly completes it, to both oam and Node. A Node host keeps `inherit`,
- * which hands over the same fds untouched.
- *
- * The discovery path PREFERS a fresh oam; it does not guarantee one. If it
- * fails -- no usable binary found, or a spawn that errors -- the server still
- * runs WITHOUT `--permission` under LEMONSQUEEZY_MCP_RUNTIME=auto: in-process
- * on Node or on an oam host at the floor, handed off to Node from an oam host
- * below it. That is how a requested sandbox has always degraded, and only
- * LEMONSQUEEZY_MCP_RUNTIME=oam turns it into a failure.
- *
- * WHAT REACHES STDERR
- * An unusable OAM_BIN is always named when discovery runs, whatever runs
- * instead. The discovered binaries that were passed over, and any .cmd/.bat
- * shim, are named only when NO usable oam is found -- a stale copy skipped for
- * a newer one is silent. A chosen oam that fails to spawn is always reported,
- * and so is a handoff TO NODE from an oam host below the floor. A below-floor
- * host that hands off to a newer oam prints nothing: that is an ordinary spawn
- * of the chosen oam. A dropped sandbox gets no note of its own: with nothing
- * else to report, the fallback is silent.
- *
- * THE `--permission` SANDBOX (opt-in)
- * `LEMONSQUEEZY_MCP_SANDBOX=1` runs the server under oam's permission model:
- * network limited to api.lemonsqueezy.com, filesystem denied outright.
- *
- * LEMONSQUEEZY_SINK_URL is operator-configured, so its host is parsed out and
- * added to the grant when set rather than assumed. Child-process stays denied
- * UNLESS LEMONSQUEEZY_API_KEY_COMMAND is configured -- that feature shells out
- * to fetch the key, so the grant is tied to the feature instead of handed over
- * unconditionally.
- *
- * Opt-in, not default, because a wrong grant does not fail loudly. oam denies a
- * non-granted environment variable by making it ABSENT from process.env rather
- * than throwing, so an under-granted LEMONSQUEEZY_API_KEY reads as
- * "unauthenticated" rather than "denied". The env list is derived from what the
- * shipped bundle actually reads -- keep it in step with the bundle.
- *
- * MINIMUM OAM VERSION
- * The latest oam release, 0.15.2 -- bump OAM_MIN when oam ships a newer one.
- * Only the current oam is used and verified; an older one is never served on.
- * The floor is not cosmetic: before 0.9.0 `child_process.execFile` ran its
- * arguments through a SHELL, `exec` accepted `timeout` and ignored it,
- * `spawnSync` truncated at `maxBuffer` while reporting success, and
- * `stdio: 'inherit'`/`'ignore'` both behaved as `'pipe'`. This server shells
- * out only when LEMONSQUEEZY_API_KEY_COMMAND is configured, so the execFile bug
- * was reachable on exactly that path -- the command's arguments were re-split
- * by a shell.
- *
- * SELECTION
- *   LEMONSQUEEZY_MCP_RUNTIME=auto   newest usable oam, else Node (default)
- *   LEMONSQUEEZY_MCP_RUNTIME=oam    newest usable oam, else exit with an error
- *                                   (already running on oam at the floor
- *                                   satisfies it, unless the sandbox is on)
- *   LEMONSQUEEZY_MCP_RUNTIME=node   Node: in THIS process on Node, handed off
- *                                   to Node on PATH when THIS process is oam
- *   LEMONSQUEEZY_MCP_SANDBOX=1      spawn a fresh oam under --permission
- *   OAM_BIN=/path/to/oam            use this oam when it is usable, before
- *                                   discovery
- * The runtime value is case-insensitive; anything else behaves like `auto`.
- */
-
-import { execFileSync, spawn } from "node:child_process";
-import { existsSync, realpathSync } from "node:fs";
-import { constants, homedir } from "node:os";
-import { delimiter, join } from "node:path";
-import { fileURLToPath } from "node:url";
-
-/** Oldest oam this server is served on. See MINIMUM OAM VERSION above. */
-const OAM_MIN = [0, 15, 2];
-
-/**
- * Bound on each `oam --version` probe. A healthy oam answers in milliseconds;
- * the bound only exists so a wedged binary on PATH cannot hang the launch.
- */
-const VERSION_PROBE_TIMEOUT_MS = 5_000;
-
-// Two forms, deliberately. `import()` on Windows REJECTS a bare `C:\...` path
-// with ERR_UNSUPPORTED_ESM_URL_SCHEME (it reads `c:` as a protocol), so the
-// in-process fallback must use the file:// URL. spawn() needs a real path.
-const SERVER_URL = new URL("../dist/index.js", import.meta.url);
-const SERVER_ENTRY = fileURLToPath(SERVER_URL);
-const isWin = process.platform === "win32";
-const exe = isWin ? "oam.exe" : "oam";
-
-/** Identity for de-duplicating paths: resolved, and case-folded on Windows. */
-function pathKey(p) {
-  let key = p;
-  try {
-    key = realpathSync(p);
-  } catch {
-    // Unresolvable: fall back to the literal path.
-  }
-  return isWin ? key.toLowerCase() : key;
-}
-
-/**
- * Every oam binary discovery can see, in search order, de-duplicated. Stat-only,
- * never a subprocess.
- *
- * Installed locations come BEFORE PATH, so when two binaries report the same
- * version the installed copy wins the tie -- a dev build on PATH is replaced
- * underneath running processes by cargo. Both forms are checked on Windows: the
- * installer defaults to %LOCALAPPDATA%\oam\bin there, but oam's docs name
- * ~/.oam/bin first and OAM_INSTALL_DIR can pick either.
- *
- * PATH is resolved manually rather than by spawning `which`/`where`, which
- * would cost a subprocess on every launch just to decide whether to spawn.
- *
- * 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. A
- * skipped shim is still reported when no usable oam is found -- see findOamShim.
- */
-function discoverOamPaths() {
-  const installed = [join(homedir(), ".oam", "bin", exe)];
-  if (isWin) {
-    installed.unshift(join(process.env.LOCALAPPDATA ?? join(homedir(), "AppData", "Local"), "oam", "bin", exe));
-  }
-  const onPath = (process.env.PATH ?? "")
-    .split(delimiter)
-    .filter(Boolean)
-    .map((dir) => join(dir, exe));
-  const seen = new Set();
-  const found = [];
-  for (const candidate of [...installed, ...onPath]) {
-    if (!existsSync(candidate)) continue;
-    const key = pathKey(candidate);
-    if (seen.has(key)) continue;
-    seen.add(key);
-    found.push(candidate);
-  }
-  return found;
-}
-
-/**
- * Version text -> [major, minor, patch], or null when it holds no version.
- * A pre-release suffix (0.9.0-rc.1) truncates to its base version.
- *
- * Shared by the two places a version is read -- a discovered binary's
- * `oam --version` output ("oam 0.15.1") and the host's own
- * `process.versions.oam` ("0.15.1") -- so they cannot disagree about what a
- * version string means, or which floor it has to clear.
- */
-function parseVersion(text) {
-  const m = /(\d+)\.(\d+)\.(\d+)/.exec(text);
-  return m ? [Number(m[1]), Number(m[2]), Number(m[3])] : null;
-}
-
-/** `oam --version` -> [major, minor, patch], or null when it cannot be read. */
-function oamVersion(cmd) {
-  try {
-    const out = execFileSync(cmd, ["--version"], {
-      encoding: "utf-8",
-      stdio: ["ignore", "pipe", "ignore"],
-      timeout: VERSION_PROBE_TIMEOUT_MS,
-      windowsHide: true,
-    });
-    return parseVersion(out);
-  } catch {
-    // Not executable, wrong arch, wedged, or deleted since the stat. Caller degrades.
-    return null;
-  }
-}
-
-/** True when `v` is at least `min`, comparing major/minor/patch in order. */
-function atLeast(v, min) {
-  if (!v) return false;
-  for (let i = 0; i < min.length; i++) {
-    if (v[i] > min[i]) return true;
-    if (v[i] < min[i]) return false;
-  }
-  return true;
-}
-
-/**
- * The newest candidate at or above the floor, or null. `candidates` is
- * `{ path, version }[]` in search order, `version` null when unreadable.
- * Strictly-greater replaces, so a tie keeps the earlier candidate.
- *
- * Pure on purpose, like runtimePlan: the choice is testable without binaries.
- */
-function pickNewest(candidates) {
-  let best = null;
-  for (const candidate of candidates) {
-    if (!atLeast(candidate.version, OAM_MIN)) continue;
-    if (!best || !atLeast(best.version, candidate.version)) best = candidate;
-  }
-  return best;
-}
-
-/**
- * Where the server runs, decided BEFORE any discovery:
- *   "in-process"   import it into THIS process
- *   "discover"     choose an oam and spawn it, or fall back
- *   "handoff-node" hand it off to Node on PATH: THIS process is an oam and
- *                  Node was asked for
- *
- * `hostOam` is `process.versions.oam`: oam's own key, absent on Node. An oam
- * host whose version cannot be read is treated as below the floor -- it never
- * proved it is a supported oam. `sandbox` is whether a spawn would carry flags
- * only a fresh oam can apply; see ALREADY RUNNING ON OAM above for why that
- * alone forces the discovery path, and why that path can still end without
- * them. The floor is OAM_MIN itself, not a parameter, so a host oam and a
- * discovered one can never be held to different minimums.
- *
- * Pure on purpose: every input is passed in, so the whole decision is testable
- * without booting a runtime.
- */
-function runtimePlan({ mode, hostOam, sandbox }) {
-  const onOam = hostOam !== undefined;
-  if (mode === "node") return onOam ? "handoff-node" : "in-process";
-  if (sandbox) return "discover";
-  return atLeast(parseVersion(hostOam ?? ""), OAM_MIN) ? "in-process" : "discover";
-}
-
-/**
- * The `--permission` grant list, or [] when the sandbox is not requested.
- *
- * These are oam's PROCESS-level flags: they belong before the `run` subcommand,
- * not after it. `oam run --permission file.js` is rejected outright, which is a
- * good failure but only because it is loud -- ordering here is load-bearing.
- *
- * Net grants prefix-match `host` for fetch and `host:port` for sockets.
- * A denied environment variable is ABSENT from process.env rather than throwing,
- * so the env list below is derived from what the bundle actually reads; trimming
- * it produces silent misbehaviour, not a clear denial.
- */
-function sandboxFlags() {
-  if (process.env.LEMONSQUEEZY_MCP_SANDBOX !== "1") return [];
-
-  const hosts = ["api.lemonsqueezy.com"];
-  // LEMONSQUEEZY_SINK_URL is operator-configured, so its host has to be learned, not assumed.
-  if (process.env.LEMONSQUEEZY_SINK_URL) {
-    try {
-      const { hostname } = new URL(process.env.LEMONSQUEEZY_SINK_URL);
-      if (hostname && !hosts.includes(hostname)) hosts.push(hostname);
-    } catch {
-      // Malformed URL: the feature is already broken on its own terms; adding
-      // nothing here keeps the grant honest rather than guessing a host.
-    }
-  }
-  const netFlag = `--allow-net=${hosts.join(",")}`;
-
-  const env = [
-    "LEMONSQUEEZY_ALLOWED_STORE_IDS",
-    "LEMONSQUEEZY_API_KEY",
-    "LEMONSQUEEZY_API_KEY_COMMAND",
-    "LEMONSQUEEZY_DESTRUCTIVE_RATE_LIMIT",
-    "LEMONSQUEEZY_DISABLE_CLASSES",
-    "LEMONSQUEEZY_LOG",
-    "LEMONSQUEEZY_MAX_REFUND_AMOUNT_CENTS",
-    "LEMONSQUEEZY_RATE_LIMIT_PER_CLASS",
-    "LEMONSQUEEZY_SINK_ADMIN_TOKEN",
-    "LEMONSQUEEZY_SINK_URL",
-    "LEMONSQUEEZY_TEST_API_KEY",
-    "PATH",
-  ];
-
-  const flags = ["--permission", netFlag, `--allow-env=${env.join(",")}`];
-  // Tied to the feature that needs it, not granted unconditionally.
-  if (process.env.LEMONSQUEEZY_API_KEY_COMMAND) flags.push("--allow-child-process");
-  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. Only looked for
- * when no usable oam was found, so a shim beside a working oam.exe is never
- * mentioned. 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;
-}
-
-/** A Node binary on PATH, or null. Stat-only; used only when THIS process is oam. */
-function findNodeOnPath() {
-  const name = isWin ? "node.exe" : "node";
-  for (const dir of (process.env.PATH ?? "").split(delimiter)) {
-    if (!dir) continue;
-    const candidate = join(dir, name);
-    if (existsSync(candidate)) return candidate;
-  }
-  return null;
-}
-
-/** Why a candidate was passed over, for stderr. */
-function unusableReason(path, version, label = path) {
-  const min = OAM_MIN.join(".");
-  return version
-    ? `${label} is oam ${version.join(".")}, older than ${min}`
-    : `${label} could not be run, or did not report a version this launcher understands`;
-}
-
-/**
- * Choose the oam to spawn: a usable OAM_BIN, else the newest usable discovered
- * binary. Returns the choice (or null) plus stderr notes: `overrideNote` about
- * an unusable OAM_BIN, and `skipped` describing what was found and rejected
- * when nothing was usable.
- */
-function chooseOam() {
-  const override = process.env.OAM_BIN;
-  let overrideNote = null;
-  if (override) {
-    if (!existsSync(override)) {
-      overrideNote = `OAM_BIN=${override} does not exist`;
-    } else {
-      const version = oamVersion(override);
-      if (atLeast(version, OAM_MIN)) return { chosen: { path: override, version }, overrideNote, skipped: [] };
-      overrideNote = unusableReason(override, version, `OAM_BIN=${override}`);
-    }
-  }
-  const overrideKey = override ? pathKey(override) : null;
-  const candidates = discoverOamPaths()
-    .filter((path) => pathKey(path) !== overrideKey)
-    .map((path) => ({ path, version: oamVersion(path) }));
-  const chosen = pickNewest(candidates);
-  const skipped = chosen ? [] : candidates.map((c) => unusableReason(c.path, c.version));
-  return { chosen, overrideNote, skipped };
-}
-
-/** 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. aws-mcp does exactly this. 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);
-}
-
-// ONE reporter for every failed in-process fallback. 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 -- replacing this launcher's
-// diagnostic with a raw stack trace.
-const fallbackFailed = (e) => {
-  process.stderr.write(`lemonsqueezy-mcp: in-process fallback failed (${e?.message ?? e})\n`);
-  process.exitCode = 1;
-};
-
-/**
- * Spawn the server in a child runtime and mirror its lifetime.
- *
- * `onLaunchFailed(err)` runs when the child could not be started at all; it is
- * never called once the child is running, which would double-start the server
- * on the same stdio.
- */
-async function launchChild(cmd, args, onLaunchFailed) {
-  // Any spawn from an oam host pipes. Below the floor its `stdio: 'inherit'`
-  // does not hand over the fds. A supported host only gets here in two cases:
-  // the sandbox asked for a fresh oam, or LEMONSQUEEZY_MCP_RUNTIME=node handed
-  // the server off to Node (handOffToNode). See ALREADY RUNNING ON OAM.
-  const piped = process.versions.oam !== undefined;
-  let child = null;
-  try {
-    child = spawn(cmd, args, {
-      // 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. Piping preserves both as well: bytes are copied
-      // unchanged, and stdin's end propagates to the child.
-      stdio: piped ? ["pipe", "pipe", "pipe"] : "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.
-    await onLaunchFailed(err).catch(fallbackFailed);
-    return;
-  }
-
-  // If the runtime cannot be executed at all (deleted between the version probe
-  // and the spawn, wrong arch, permission), fall back rather than failing the
-  // whole server. `spawned` prevents falling back AFTER the child started.
-  //
-  // Everything that assumes a live child waits for 'spawn'. A failed spawn
-  // still emits 'close' (after 'error', with the negative errno as its code), so
-  // an unguarded close handler would process.exit() out from under the fallback
-  // onLaunchFailed has just started. And stdin piped into a child that never ran
-  // takes input away from that fallback: measured with the in-process fallback,
-  // the host's first request was answered and the next one never arrived. Until
-  // 'spawn', process.stdin has no reader and simply stays paused.
-  let spawned = false;
-  child.on("spawn", () => {
-    spawned = true;
-    if (piped) {
-      process.stdin.pipe(child.stdin);
-      child.stdout.pipe(process.stdout);
-      child.stderr.pipe(process.stderr);
-    }
-    forwardSignals();
-  });
-  child.on("error", (err) => {
-    if (spawned) return;
-    onLaunchFailed(err).catch(fallbackFailed);
-  });
-  // A child that exits before reading everything closes its stdin; the
-  // resulting EPIPE is not worth crashing over.
-  child.stdin?.on("error", () => {});
-
-  // 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;
-  function forwardSignals() {
-    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);
-      });
-    }
-  }
-
-  // Piped: wait for 'close', so the child's last stdout bytes are copied out
-  // before this process exits. Inherited: 'exit' is enough, the fds were never
-  // ours to drain. Either way, only for a child that actually ran -- see the
-  // 'spawn' handler above.
-  child.on(piped ? "close" : "exit", (code, signal) => {
-    if (!spawned) return;
-    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);
-  });
-}
-
-/**
- * Hand the server to Node on PATH. Only reachable when THIS process is oam --
- * one below the floor, or any oam under LEMONSQUEEZY_MCP_RUNTIME=node -- so
- * there is no in-process option left.
- */
-async function handOffToNode(reason) {
-  const node = findNodeOnPath();
-  if (!node) {
-    await errSync(
-      `lemonsqueezy-mcp: ${reason}, and no Node was found on PATH to run the server instead.\n` +
-        `Run \`oam self-update\` to get oam ${OAM_MIN.join(".")} or newer, or launch this command with node.\n`,
-    );
-    process.exit(1);
-  }
-  if (reason) await errSync(`lemonsqueezy-mcp: ${reason}; running on ${node} instead.\n`);
-  await launchChild(node, [SERVER_ENTRY, ...process.argv.slice(2)], async (err) => {
-    await errSync(`lemonsqueezy-mcp: failed to launch Node at ${node} (${err?.message ?? err})\n`);
-    process.exit(1);
-  });
-}
-
-/**
- * No oam was spawned, under a mode that allows falling back. `note` is what was
- * passed over, or "" when there is nothing to say. `newerFound` is true when a
- * usable oam WAS chosen and only its launch failed, so the below-floor handoff
- * note does not claim that no newer oam exists.
- *
- * Node, and an oam host at the floor, serve in-process. The latter is reachable
- * only with the sandbox requested -- a supported host otherwise never reaches
- * discovery -- so it serves WITHOUT `--permission`, as a requested sandbox
- * always has when no fresh oam could be started. An oam host below the floor
- * never serves and hands off to Node.
- */
-async function fallBack(hostOam, note, newerFound = false) {
-  if (hostOam === undefined) {
-    if (note) await errSync(`lemonsqueezy-mcp: ${note}; using Node instead.\n`);
-    await runInProcess();
-    return;
-  }
-  if (atLeast(parseVersion(hostOam), OAM_MIN)) {
-    if (note) await errSync(`lemonsqueezy-mcp: ${note}; serving on this oam ${hostOam} without --permission.\n`);
-    await runInProcess();
-    return;
-  }
-  const why = `this process is oam ${hostOam}, older than ${OAM_MIN.join(".")}${newerFound ? "" : ", and no newer oam was found"}`;
-  await handOffToNode(`${note ? `${note}; ` : ""}${why}`);
-}
-
-const mode = (process.env.LEMONSQUEEZY_MCP_RUNTIME ?? "auto").toLowerCase();
-const hostOam = process.versions.oam;
-
-// Computed ONCE and reused by the spawn below, so "would the spawn carry
-// --permission" cannot drift from what the spawn actually passes.
-const sandbox = sandboxFlags();
-const plan = runtimePlan({ mode, hostOam, sandbox: sandbox.length > 0 });
-
-if (plan === "in-process") {
-  await runInProcess();
-} else if (plan === "handoff-node") {
-  const belowFloor = !atLeast(parseVersion(hostOam), OAM_MIN);
-  await handOffToNode(belowFloor ? `this process is oam ${hostOam}, older than ${OAM_MIN.join(".")}` : "");
-} else {
-  const { chosen, overrideNote, skipped } = chooseOam();
-
-  if (chosen) {
-    if (overrideNote) {
-      await errSync(`lemonsqueezy-mcp: ${overrideNote}; using ${chosen.path} (oam ${chosen.version.join(".")}).\n`);
-    }
-    // `--` separates oam's own flags from the script's argv, so `lemonsqueezy-mcp
-    // --version` and any host-supplied flags survive the hop unchanged. The
-    // sandbox flags are process-level, so they go BEFORE `run`.
-    await launchChild(chosen.path, [...sandbox, "run", SERVER_ENTRY, "--", ...process.argv.slice(2)], async (err) => {
-      const failed = `failed to launch oam at ${chosen.path} (${err?.message ?? err})`;
-      if (mode === "oam") {
-        await errSync(`lemonsqueezy-mcp: ${failed}\n`);
-        process.exit(1);
-      }
-      await fallBack(hostOam, failed, true);
-    });
-  } else {
-    const shim = findOamShim();
-    const notes = [
-      ...(overrideNote ? [overrideNote] : []),
-      ...skipped,
-      ...(shim
-        ? [
-            `found ${shim}, but Node cannot execute a .cmd/.bat directly -- install the native oam binary, or point OAM_BIN at one`,
-          ]
-        : []),
-    ];
-    if (mode === "oam") {
-      await errSync(
-        `lemonsqueezy-mcp: LEMONSQUEEZY_MCP_RUNTIME=oam but no usable oam (${OAM_MIN.join(".")} or newer) was found.\n` +
-          notes.map((note) => `  ${note}\n`).join("") +
-          "Install or update from https://oamjs.org, set OAM_BIN=/path/to/oam, or use LEMONSQUEEZY_MCP_RUNTIME=node.\n",
-      );
-      process.exit(1);
-    }
-    // auto: falling back is correct, but silence is how someone never learns
-    // their OAM_BIN is wrong or their oam is too old to use.
-    await fallBack(hostOam, notes.join("; ")).catch(fallbackFailed);
-  }
-}
+#!/usr/bin/env node
+/**
+ * Runtime launcher for @yawlabs/lemonsqueezy-mcp.
+ *
+ * Prefers the newest usable oam runtime (https://oamjs.org) and falls back to
+ * Node. It never serves on an oam older than the floor below.
+ *
+ *
+ * WHY THE FALLBACK COSTS NOTHING
+ * npm has already started Node to run this launcher, so falling back is a
+ * plain `import()` of the server into THIS process: no extra spawn, no extra
+ * startup, byte-identical to invoking dist/index.js directly. Finding the
+ * candidates is stat-only, so a machine without oam never pays for a
+ * subprocess.
+ *
+ * WHAT THE OAM PATH COSTS
+ * Reaching oam through an npm `bin` means Node boots first, every oam binary
+ * found is asked for its version, and then oam boots to serve -- so the
+ * launcher is slower than pointing a host at oam directly. Measured on
+ * npmjs-mcp (windows-arm64, n=12 medians, spawn to first MCP initialize):
+ * oam 116ms, node 172ms, launcher 243ms. It exists for `npx` convenience.
+ *
+ * For an MCP host config, point straight at oam and skip this file:
+ *   { "command": "oam", "args": ["run", "<abs>/dist/index.js"] }
+ *
+ * WHICH OAM
+ * OAM_BIN, when set and usable, is used as given. Otherwise every oam binary
+ * discovery can see -- the installed locations, then PATH -- is asked for its
+ * version, and the NEWEST one at or above the floor wins; a tie keeps search
+ * order. Taking the first binary found instead let a stale copy early in the
+ * search order hide a current one later: with oam 0.9.0 installed in ~/.oam/bin
+ * and 0.15.2 on PATH, the launcher bound to 0.9.0 because installed locations
+ * are searched first.
+ *
+ * An OAM_BIN that does not exist, is below the floor, or will not run is named
+ * on stderr and discovery carries on. It used to stop everything: a typo in
+ * OAM_BIN meant Node, with no hint why.
+ *
+ * ALREADY RUNNING ON OAM
+ * A host can resolve this package's `bin` and launch `oam run <this file>`
+ * instead of `node <this file>` -- Yaw MCP does, and so does oam's sidecar
+ * regression matrix. When `process.versions.oam` clears the floor, the server
+ * is imported into THIS process exactly as the Node fallback is -- no
+ * discovery, no `oam --version` probe, no second oam. OAM_BIN is a discovery
+ * input, so it is not consulted on that path: the host has already chosen
+ * which oam runs.
+ *
+ * LEMONSQUEEZY_MCP_SANDBOX=1 is the exception, deliberately. `--permission` is
+ * a process-level flag that only a FRESH oam can apply, so a supported oam host
+ * still takes the discovery path and spawns one -- skipping straight to
+ * in-process there would drop the sandbox without a word, a security downgrade
+ * dressed up as an optimisation.
+ *
+ * A host oam BELOW the floor never serves. It hands the server off to the
+ * newest usable oam, or to Node found on PATH, or exits with an error when
+ * there is neither.
+ *
+ * Any handoff from an oam host PIPES stdio rather than inheriting it. Before
+ * 0.9.0 oam treated `stdio: 'inherit'` as `'pipe'`, so an inherited handoff
+ * from such a host connected the child to pipes nobody reads: measured with a
+ * real oam 0.8.2 host, the MCP handshake never answered. Piping the streams
+ * explicitly completes it, to both oam and Node. A Node host keeps `inherit`,
+ * which hands over the same fds untouched.
+ *
+ * The discovery path PREFERS a fresh oam; it does not guarantee one. If it
+ * fails -- no usable binary found, or a spawn that errors -- the server still
+ * runs WITHOUT `--permission` under LEMONSQUEEZY_MCP_RUNTIME=auto: in-process
+ * on Node or on an oam host at the floor, handed off to Node from an oam host
+ * below it. That is how a requested sandbox has always degraded, and only
+ * LEMONSQUEEZY_MCP_RUNTIME=oam turns it into a failure.
+ *
+ * WHAT REACHES STDERR
+ * An unusable OAM_BIN is always named when discovery runs, whatever runs
+ * instead. The discovered binaries that were passed over, and any .cmd/.bat
+ * shim, are named only when NO usable oam is found -- a stale copy skipped for
+ * a newer one is silent. A chosen oam that fails to spawn is always reported,
+ * and so is a handoff TO NODE from an oam host below the floor. A below-floor
+ * host that hands off to a newer oam prints nothing: that is an ordinary spawn
+ * of the chosen oam. A dropped sandbox gets no note of its own: with nothing
+ * else to report, the fallback is silent.
+ *
+ * THE `--permission` SANDBOX (opt-in)
+ * `LEMONSQUEEZY_MCP_SANDBOX=1` runs the server under oam's permission model:
+ * network limited to api.lemonsqueezy.com, filesystem denied outright.
+ *
+ * LEMONSQUEEZY_SINK_URL is operator-configured, so its host is parsed out and
+ * added to the grant when set rather than assumed. Child-process stays denied
+ * UNLESS LEMONSQUEEZY_API_KEY_COMMAND is configured -- that feature runs the
+ * key command as a child process (execFile, no shell), so the grant is tied to
+ * the feature instead of handed over unconditionally.
+ *
+ * Opt-in, not default, because a wrong grant does not fail loudly. oam denies a
+ * non-granted environment variable by making it ABSENT from process.env rather
+ * than throwing, so an under-granted LEMONSQUEEZY_API_KEY reads as
+ * "unauthenticated" rather than "denied". The env list is derived from what the
+ * shipped bundle actually reads -- keep it in step with the bundle.
+ *
+ * MINIMUM OAM VERSION
+ * OAM_MIN, 0.15.2, is a floor: the oam this server was last verified on, not
+ * a claim that it is the newest oam. Raise it once a newer oam has been
+ * re-verified here (handshake and all 64 tools through this launcher). The
+ * server only runs on an oam at or above the floor; an older one is never
+ * served on. The floor is not cosmetic: before 0.9.0 `child_process.execFile`
+ * ran its arguments through a SHELL, `exec` accepted `timeout` and ignored it,
+ * `spawnSync` truncated at `maxBuffer` while reporting success, and
+ * `stdio: 'inherit'`/`'ignore'` both behaved as `'pipe'`. This server starts a
+ * child process only when LEMONSQUEEZY_API_KEY_COMMAND is configured (execFile,
+ * deliberately without a shell), so the execFile bug was reachable on exactly
+ * that path -- the command's arguments were re-split by a shell anyway.
+ *
+ * SELECTION
+ *   LEMONSQUEEZY_MCP_RUNTIME=auto   newest usable oam, else Node (default)
+ *   LEMONSQUEEZY_MCP_RUNTIME=oam    newest usable oam, else exit with an error
+ *                                   (already running on oam at the floor
+ *                                   satisfies it, unless the sandbox is on)
+ *   LEMONSQUEEZY_MCP_RUNTIME=node   Node: in THIS process on Node, handed off
+ *                                   to Node on PATH when THIS process is oam
+ *   LEMONSQUEEZY_MCP_SANDBOX=1      spawn a fresh oam under --permission
+ *   OAM_BIN=/path/to/oam            use this oam when it is usable, before
+ *                                   discovery
+ * The runtime value is case-insensitive; anything else behaves like `auto`.
+ */
+
+import { execFileSync, spawn } from "node:child_process";
+import { existsSync, realpathSync } from "node:fs";
+import { constants, homedir } from "node:os";
+import { delimiter, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+/** Oldest oam this server is served on. See MINIMUM OAM VERSION above. */
+const OAM_MIN = [0, 15, 2];
+
+/**
+ * Bound on each `oam --version` probe. A healthy oam answers in milliseconds;
+ * the bound only exists so a wedged binary on PATH cannot hang the launch.
+ */
+const VERSION_PROBE_TIMEOUT_MS = 5_000;
+
+// Two forms, deliberately. `import()` on Windows REJECTS a bare `C:\...` path
+// with ERR_UNSUPPORTED_ESM_URL_SCHEME (it reads `c:` as a protocol), so the
+// in-process fallback must use the file:// URL. spawn() needs a real path.
+const SERVER_URL = new URL("../dist/index.js", import.meta.url);
+const SERVER_ENTRY = fileURLToPath(SERVER_URL);
+const isWin = process.platform === "win32";
+const exe = isWin ? "oam.exe" : "oam";
+
+/** Identity for de-duplicating paths: resolved, and case-folded on Windows. */
+function pathKey(p) {
+  let key = p;
+  try {
+    key = realpathSync(p);
+  } catch {
+    // Unresolvable: fall back to the literal path.
+  }
+  return isWin ? key.toLowerCase() : key;
+}
+
+/**
+ * Every oam binary discovery can see, in search order, de-duplicated. Stat-only,
+ * never a subprocess.
+ *
+ * Installed locations come BEFORE PATH, so when two binaries report the same
+ * version the installed copy wins the tie -- a dev build on PATH is replaced
+ * underneath running processes by cargo. Both forms are checked on Windows: the
+ * installer defaults to %LOCALAPPDATA%\oam\bin there, but oam's docs name
+ * ~/.oam/bin first and OAM_INSTALL_DIR can pick either.
+ *
+ * PATH is resolved manually rather than by spawning `which`/`where`, which
+ * would cost a subprocess on every launch just to decide whether to spawn.
+ *
+ * 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. A
+ * skipped shim is still reported when no usable oam is found -- see findOamShim.
+ */
+function discoverOamPaths() {
+  const installed = [join(homedir(), ".oam", "bin", exe)];
+  if (isWin) {
+    installed.unshift(join(process.env.LOCALAPPDATA ?? join(homedir(), "AppData", "Local"), "oam", "bin", exe));
+  }
+  const onPath = (process.env.PATH ?? "")
+    .split(delimiter)
+    .filter(Boolean)
+    .map((dir) => join(dir, exe));
+  const seen = new Set();
+  const found = [];
+  for (const candidate of [...installed, ...onPath]) {
+    if (!existsSync(candidate)) continue;
+    const key = pathKey(candidate);
+    if (seen.has(key)) continue;
+    seen.add(key);
+    found.push(candidate);
+  }
+  return found;
+}
+
+/**
+ * Version text -> [major, minor, patch], or null when it holds no version.
+ * A pre-release suffix (0.9.0-rc.1) truncates to its base version.
+ *
+ * Shared by the two places a version is read -- a discovered binary's
+ * `oam --version` output ("oam 0.15.1") and the host's own
+ * `process.versions.oam` ("0.15.1") -- so they cannot disagree about what a
+ * version string means, or which floor it has to clear.
+ */
+function parseVersion(text) {
+  const m = /(\d+)\.(\d+)\.(\d+)/.exec(text);
+  return m ? [Number(m[1]), Number(m[2]), Number(m[3])] : null;
+}
+
+/** `oam --version` -> [major, minor, patch], or null when it cannot be read. */
+function oamVersion(cmd) {
+  try {
+    const out = execFileSync(cmd, ["--version"], {
+      encoding: "utf-8",
+      stdio: ["ignore", "pipe", "ignore"],
+      timeout: VERSION_PROBE_TIMEOUT_MS,
+      windowsHide: true,
+    });
+    return parseVersion(out);
+  } catch {
+    // Not executable, wrong arch, wedged, or deleted since the stat. Caller degrades.
+    return null;
+  }
+}
+
+/** True when `v` is at least `min`, comparing major/minor/patch in order. */
+function atLeast(v, min) {
+  if (!v) return false;
+  for (let i = 0; i < min.length; i++) {
+    if (v[i] > min[i]) return true;
+    if (v[i] < min[i]) return false;
+  }
+  return true;
+}
+
+/**
+ * The newest candidate at or above the floor, or null. `candidates` is
+ * `{ path, version }[]` in search order, `version` null when unreadable.
+ * Strictly-greater replaces, so a tie keeps the earlier candidate.
+ *
+ * Pure on purpose, like runtimePlan: the choice is testable without binaries.
+ */
+function pickNewest(candidates) {
+  let best = null;
+  for (const candidate of candidates) {
+    if (!atLeast(candidate.version, OAM_MIN)) continue;
+    if (!best || !atLeast(best.version, candidate.version)) best = candidate;
+  }
+  return best;
+}
+
+/**
+ * Where the server runs, decided BEFORE any discovery:
+ *   "in-process"   import it into THIS process
+ *   "discover"     choose an oam and spawn it, or fall back
+ *   "handoff-node" hand it off to Node on PATH: THIS process is an oam and
+ *                  Node was asked for
+ *
+ * `hostOam` is `process.versions.oam`: oam's own key, absent on Node. An oam
+ * host whose version cannot be read is treated as below the floor -- it never
+ * proved it is a supported oam. `sandbox` is whether a spawn would carry flags
+ * only a fresh oam can apply; see ALREADY RUNNING ON OAM above for why that
+ * alone forces the discovery path, and why that path can still end without
+ * them. The floor is OAM_MIN itself, not a parameter, so a host oam and a
+ * discovered one can never be held to different minimums.
+ *
+ * Pure on purpose: every input is passed in, so the whole decision is testable
+ * without booting a runtime.
+ */
+function runtimePlan({ mode, hostOam, sandbox }) {
+  const onOam = hostOam !== undefined;
+  if (mode === "node") return onOam ? "handoff-node" : "in-process";
+  if (sandbox) return "discover";
+  return atLeast(parseVersion(hostOam ?? ""), OAM_MIN) ? "in-process" : "discover";
+}
+
+/**
+ * The `--permission` grant list, or [] when the sandbox is not requested.
+ *
+ * These are oam's PROCESS-level flags: they belong before the `run` subcommand,
+ * not after it. `oam run --permission file.js` is rejected outright, which is a
+ * good failure but only because it is loud -- ordering here is load-bearing.
+ *
+ * Net grants prefix-match `host` for fetch and `host:port` for sockets.
+ * A denied environment variable is ABSENT from process.env rather than throwing,
+ * so the env list below is derived from what the bundle actually reads; trimming
+ * it produces silent misbehaviour, not a clear denial.
+ */
+function sandboxFlags() {
+  if (process.env.LEMONSQUEEZY_MCP_SANDBOX !== "1") return [];
+
+  const hosts = ["api.lemonsqueezy.com"];
+  // LEMONSQUEEZY_SINK_URL is operator-configured, so its host has to be learned, not assumed.
+  if (process.env.LEMONSQUEEZY_SINK_URL) {
+    try {
+      const { hostname } = new URL(process.env.LEMONSQUEEZY_SINK_URL);
+      if (hostname && !hosts.includes(hostname)) hosts.push(hostname);
+    } catch {
+      // Malformed URL: the feature is already broken on its own terms; adding
+      // nothing here keeps the grant honest rather than guessing a host.
+    }
+  }
+  const netFlag = `--allow-net=${hosts.join(",")}`;
+
+  const env = [
+    "LEMONSQUEEZY_ALLOWED_STORE_IDS",
+    "LEMONSQUEEZY_API_KEY",
+    "LEMONSQUEEZY_API_KEY_COMMAND",
+    "LEMONSQUEEZY_DESTRUCTIVE_RATE_LIMIT",
+    "LEMONSQUEEZY_DISABLE_CLASSES",
+    "LEMONSQUEEZY_LOG",
+    "LEMONSQUEEZY_MAX_REFUND_AMOUNT_CENTS",
+    "LEMONSQUEEZY_RATE_LIMIT_PER_CLASS",
+    "LEMONSQUEEZY_SINK_ADMIN_TOKEN",
+    "LEMONSQUEEZY_SINK_URL",
+    "LEMONSQUEEZY_TEST_API_KEY",
+    "PATH",
+  ];
+
+  const flags = ["--permission", netFlag, `--allow-env=${env.join(",")}`];
+  // Tied to the feature that needs it, not granted unconditionally.
+  if (process.env.LEMONSQUEEZY_API_KEY_COMMAND) flags.push("--allow-child-process");
+  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. Only looked for
+ * when no usable oam was found, so a shim beside a working oam.exe is never
+ * mentioned. 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;
+}
+
+/** A Node binary on PATH, or null. Stat-only; used only when THIS process is oam. */
+function findNodeOnPath() {
+  const name = isWin ? "node.exe" : "node";
+  for (const dir of (process.env.PATH ?? "").split(delimiter)) {
+    if (!dir) continue;
+    const candidate = join(dir, name);
+    if (existsSync(candidate)) return candidate;
+  }
+  return null;
+}
+
+/** Why a candidate was passed over, for stderr. */
+function unusableReason(path, version, label = path) {
+  const min = OAM_MIN.join(".");
+  return version
+    ? `${label} is oam ${version.join(".")}, older than ${min}`
+    : `${label} could not be run, or did not report a version this launcher understands`;
+}
+
+/**
+ * Choose the oam to spawn: a usable OAM_BIN, else the newest usable discovered
+ * binary. Returns the choice (or null) plus stderr notes: `overrideNote` about
+ * an unusable OAM_BIN, and `skipped` describing what was found and rejected
+ * when nothing was usable.
+ */
+function chooseOam() {
+  const override = process.env.OAM_BIN;
+  let overrideNote = null;
+  if (override) {
+    if (!existsSync(override)) {
+      overrideNote = `OAM_BIN=${override} does not exist`;
+    } else {
+      const version = oamVersion(override);
+      if (atLeast(version, OAM_MIN)) return { chosen: { path: override, version }, overrideNote, skipped: [] };
+      overrideNote = unusableReason(override, version, `OAM_BIN=${override}`);
+    }
+  }
+  const overrideKey = override ? pathKey(override) : null;
+  const candidates = discoverOamPaths()
+    .filter((path) => pathKey(path) !== overrideKey)
+    .map((path) => ({ path, version: oamVersion(path) }));
+  const chosen = pickNewest(candidates);
+  const skipped = chosen ? [] : candidates.map((c) => unusableReason(c.path, c.version));
+  return { chosen, overrideNote, skipped };
+}
+
+/** 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. aws-mcp does exactly this. 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);
+}
+
+// ONE reporter for every failed in-process fallback. 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 -- replacing this launcher's
+// diagnostic with a raw stack trace.
+const fallbackFailed = (e) => {
+  process.stderr.write(`lemonsqueezy-mcp: in-process fallback failed (${e?.message ?? e})\n`);
+  process.exitCode = 1;
+};
+
+/**
+ * Spawn the server in a child runtime and mirror its lifetime.
+ *
+ * `onLaunchFailed(err)` runs when the child could not be started at all; it is
+ * never called once the child is running, which would double-start the server
+ * on the same stdio.
+ */
+async function launchChild(cmd, args, onLaunchFailed) {
+  // Any spawn from an oam host pipes. Below the floor its `stdio: 'inherit'`
+  // does not hand over the fds. A supported host only gets here in two cases:
+  // the sandbox asked for a fresh oam, or LEMONSQUEEZY_MCP_RUNTIME=node handed
+  // the server off to Node (handOffToNode). See ALREADY RUNNING ON OAM.
+  const piped = process.versions.oam !== undefined;
+  let child = null;
+  try {
+    child = spawn(cmd, args, {
+      // 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. Piping preserves both as well: bytes are copied
+      // unchanged, and stdin's end propagates to the child.
+      stdio: piped ? ["pipe", "pipe", "pipe"] : "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.
+    await onLaunchFailed(err).catch(fallbackFailed);
+    return;
+  }
+
+  // If the runtime cannot be executed at all (deleted between the version probe
+  // and the spawn, wrong arch, permission), fall back rather than failing the
+  // whole server. `spawned` prevents falling back AFTER the child started.
+  //
+  // Everything that assumes a live child waits for 'spawn'. A failed spawn
+  // still emits 'close' (after 'error', with the negative errno as its code), so
+  // an unguarded close handler would process.exit() out from under the fallback
+  // onLaunchFailed has just started. And stdin piped into a child that never ran
+  // takes input away from that fallback: measured with the in-process fallback,
+  // the host's first request was answered and the next one never arrived. Until
+  // 'spawn', process.stdin has no reader and simply stays paused.
+  let spawned = false;
+  child.on("spawn", () => {
+    spawned = true;
+    if (piped) {
+      process.stdin.pipe(child.stdin);
+      child.stdout.pipe(process.stdout);
+      child.stderr.pipe(process.stderr);
+    }
+    forwardSignals();
+  });
+  child.on("error", (err) => {
+    if (spawned) return;
+    onLaunchFailed(err).catch(fallbackFailed);
+  });
+  // A child that exits before reading everything closes its stdin; the
+  // resulting EPIPE is not worth crashing over.
+  child.stdin?.on("error", () => {});
+
+  // 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;
+  function forwardSignals() {
+    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);
+      });
+    }
+  }
+
+  // Piped: wait for 'close', so the child's last stdout bytes are copied out
+  // before this process exits. Inherited: 'exit' is enough, the fds were never
+  // ours to drain. Either way, only for a child that actually ran -- see the
+  // 'spawn' handler above.
+  child.on(piped ? "close" : "exit", (code, signal) => {
+    if (!spawned) return;
+    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);
+  });
+}
+
+/**
+ * Hand the server to Node on PATH. Only reachable when THIS process is oam --
+ * one below the floor, or any oam under LEMONSQUEEZY_MCP_RUNTIME=node -- so
+ * there is no in-process option left.
+ */
+async function handOffToNode(reason) {
+  const node = findNodeOnPath();
+  if (!node) {
+    await errSync(
+      `lemonsqueezy-mcp: ${reason}, and no Node was found on PATH to run the server instead.\n` +
+        `Run \`oam self-update\` to get oam ${OAM_MIN.join(".")} or newer, or launch this command with node.\n`,
+    );
+    process.exit(1);
+  }
+  if (reason) await errSync(`lemonsqueezy-mcp: ${reason}; running on ${node} instead.\n`);
+  await launchChild(node, [SERVER_ENTRY, ...process.argv.slice(2)], async (err) => {
+    await errSync(`lemonsqueezy-mcp: failed to launch Node at ${node} (${err?.message ?? err})\n`);
+    process.exit(1);
+  });
+}
+
+/**
+ * No oam was spawned, under a mode that allows falling back. `note` is what was
+ * passed over, or "" when there is nothing to say. `newerFound` is true when a
+ * usable oam WAS chosen and only its launch failed, so the below-floor handoff
+ * note does not claim that no newer oam exists.
+ *
+ * Node, and an oam host at the floor, serve in-process. The latter is reachable
+ * only with the sandbox requested -- a supported host otherwise never reaches
+ * discovery -- so it serves WITHOUT `--permission`, as a requested sandbox
+ * always has when no fresh oam could be started. An oam host below the floor
+ * never serves and hands off to Node.
+ */
+async function fallBack(hostOam, note, newerFound = false) {
+  if (hostOam === undefined) {
+    if (note) await errSync(`lemonsqueezy-mcp: ${note}; using Node instead.\n`);
+    await runInProcess();
+    return;
+  }
+  if (atLeast(parseVersion(hostOam), OAM_MIN)) {
+    if (note) await errSync(`lemonsqueezy-mcp: ${note}; serving on this oam ${hostOam} without --permission.\n`);
+    await runInProcess();
+    return;
+  }
+  const why = `this process is oam ${hostOam}, older than ${OAM_MIN.join(".")}${newerFound ? "" : ", and no newer oam was found"}`;
+  await handOffToNode(`${note ? `${note}; ` : ""}${why}`);
+}
+
+const mode = (process.env.LEMONSQUEEZY_MCP_RUNTIME ?? "auto").toLowerCase();
+const hostOam = process.versions.oam;
+
+// Computed ONCE and reused by the spawn below, so "would the spawn carry
+// --permission" cannot drift from what the spawn actually passes.
+const sandbox = sandboxFlags();
+const plan = runtimePlan({ mode, hostOam, sandbox: sandbox.length > 0 });
+
+if (plan === "in-process") {
+  await runInProcess();
+} else if (plan === "handoff-node") {
+  const belowFloor = !atLeast(parseVersion(hostOam), OAM_MIN);
+  await handOffToNode(belowFloor ? `this process is oam ${hostOam}, older than ${OAM_MIN.join(".")}` : "");
+} else {
+  const { chosen, overrideNote, skipped } = chooseOam();
+
+  if (chosen) {
+    if (overrideNote) {
+      await errSync(`lemonsqueezy-mcp: ${overrideNote}; using ${chosen.path} (oam ${chosen.version.join(".")}).\n`);
+    }
+    // `--` separates oam's own flags from the script's argv, so `lemonsqueezy-mcp
+    // --version` and any host-supplied flags survive the hop unchanged. The
+    // sandbox flags are process-level, so they go BEFORE `run`.
+    await launchChild(chosen.path, [...sandbox, "run", SERVER_ENTRY, "--", ...process.argv.slice(2)], async (err) => {
+      const failed = `failed to launch oam at ${chosen.path} (${err?.message ?? err})`;
+      if (mode === "oam") {
+        await errSync(`lemonsqueezy-mcp: ${failed}\n`);
+        process.exit(1);
+      }
+      await fallBack(hostOam, failed, true);
+    });
+  } else {
+    const shim = findOamShim();
+    const notes = [
+      ...(overrideNote ? [overrideNote] : []),
+      ...skipped,
+      ...(shim
+        ? [
+            `found ${shim}, but Node cannot execute a .cmd/.bat directly -- install the native oam binary, or point OAM_BIN at one`,
+          ]
+        : []),
+    ];
+    if (mode === "oam") {
+      await errSync(
+        `lemonsqueezy-mcp: LEMONSQUEEZY_MCP_RUNTIME=oam but no usable oam (${OAM_MIN.join(".")} or newer) was found.\n` +
+          notes.map((note) => `  ${note}\n`).join("") +
+          "Install or update from https://oamjs.org, set OAM_BIN=/path/to/oam, or use LEMONSQUEEZY_MCP_RUNTIME=node.\n",
+      );
+      process.exit(1);
+    }
+    // auto: falling back is correct, but silence is how someone never learns
+    // their OAM_BIN is wrong or their oam is too old to use.
+    await fallBack(hostOam, notes.join("; ")).catch(fallbackFailed);
+  }
+}