feat: pmxt.server namespace + fix ServerManager parallel-init race

Adds a single namespaced entry point for sidecar lifecycle in both the
TypeScript and Python SDKs:

  pmxt.server.status()   structured snapshot (running, pid, port, version, uptime)
  pmxt.server.health()   fast /health probe
  pmxt.server.start()    idempotent start
  pmxt.server.stop()     stop and clean up the lock file
  pmxt.server.restart()  stop + start
  pmxt.server.logs(n)    tail ~/.pmxt/server.log

pmxt-ensure-server now redirects spawned sidecar stdio to
~/.pmxt/server.log so logs() has something to read. Previously stdio
was dropped and boot crashes left no trace.

Also fixes a long-standing race in ServerManager.ensureServerRunning().
Creating multiple Exchange instances in parallel caused every request
to return 401 Unauthorized: each Exchange constructed its own
ServerManager, each one called ensureServerRunning() concurrently,
every call saw 'no server running', every call spawned its own sidecar
via pmxt-ensure-server, and the lock file ended up pointing at
whichever spawn wrote last. Each Exchange had already captured its
basePath at construction time, so most requests hit a sidecar whose
access token did NOT match the token later read from the lock file.

Fix is process-wide coalescing:
- TypeScript: static Promise<void> | null cache on ServerManager.
  Concurrent callers await the same in-flight promise; the cache is
  cleared on settle so later calls can re-check sidecar state.
- Python: class-level threading.Lock wrapping the entire
  check-and-spawn critical section. The is-alive check is
  re-evaluated inside the lock so threads that lose the race observe
  the sidecar that the winning thread just started.

Fully backwards compatible: pmxt.stopServer() / pmxt.restartServer()
(and stop_server / restart_server in Python) remain first-class
aliases. No deprecation, no warnings.

Author: realfishsam

changelog.md

@@ -2,6 +2,39 @@
 
 All notable changes to this project will be documented in this file.
 
+## [2.26.0] - 2026-04-08
+
+### Fixed
+
+- **`ServerManager.ensureServerRunning()` race condition (TypeScript and Python SDKs)**: Creating multiple `Exchange` instances in parallel (e.g. `const p = new Polymarket(); const k = new Kalshi(); const l = new Limitless();`) caused every request to return `401 Unauthorized`. Each `Exchange` constructed its own `ServerManager` and each one called `ensureServerRunning()` concurrently. Every call saw "no server running", every call spawned its own sidecar via `pmxt-ensure-server`, and the lock file ended up pointing at whichever spawn wrote last — but each `Exchange` had already captured its own `basePath` at construction time, so most requests hit a sidecar whose access token did NOT match the token later read from the lock file.
+
+  Fix is process-wide coalescing inside `ServerManager`:
+  - **TypeScript**: `ensureServerRunning()` now uses a static `Promise | null` cache. Concurrent callers await the same in-flight promise; the cache is cleared on settle so later calls can re-check the sidecar state.
+  - **Python**: `ensure_server_running()` now holds a class-level `threading.Lock` for the entire check-and-spawn critical section. The "is the server already running?" check is re-evaluated inside the lock so threads that lose the race observe the sidecar that the winning thread just started.
+
+### Added
+
+- **`pmxt.server` namespace for sidecar lifecycle management** (TypeScript and Python SDKs): A single, discoverable namespace for managing the background sidecar. All six commands are available identically in both SDKs:
+  - `pmxt.server.status()` — Structured snapshot: `{ running, pid, port, version, uptimeSeconds, lockFile }`. Returns a fresh object on every call (no shared mutable state).
+  - `pmxt.server.health()` — Returns `true` if the sidecar responds to `/health`, `false` otherwise. Fast, no side effects.
+  - `pmxt.server.start()` — Idempotently starts the sidecar. No-op if one is already running.
+  - `pmxt.server.stop()` — Stops the sidecar and removes the lock file.
+  - `pmxt.server.restart()` — Stop + start.
+  - `pmxt.server.logs(n = 50)` — Returns the last `n` lines from `~/.pmxt/server.log`, or an empty list if the launcher never wrote a log file.
+
+  Motivation: sidecar lifecycle is a real surface users hit regularly — stale lock files, zombie sidecars from crashed parents, version mismatches, and race conditions when multiple `Exchange` instances boot in parallel. Previously users had to reach into `ServerManager` directly or shell out to `ps` / `lsof` to diagnose. `pmxt.server.*` makes the lifecycle observable and controllable from a single entry point. Example:
+
+  ```typescript
+  import pmxt from 'pmxtjs';
+  const s = await pmxt.server.status();
+  if (!s.running) await pmxt.server.start();
+  console.log(await pmxt.server.logs(20));
+  ```
+
+- **Sidecar writes stdout/stderr to `~/.pmxt/server.log`**: `pmxt-ensure-server` now redirects the spawned sidecar's stdio to a log file in the `~/.pmxt/` directory so `pmxt.server.logs()` has something to read. Previously stdio was dropped (`stdio: 'ignore'`) and any crash during boot left no trace.
+
+Fully backwards compatible: the existing flat helpers `pmxt.stopServer()` / `pmxt.restartServer()` (TypeScript) and `pmxt.stop_server()` / `pmxt.restart_server()` (Python) remain first-class, fully-supported aliases for `pmxt.server.stop()` / `pmxt.server.restart()`. No deprecation, no warnings — both spellings work and will keep working.
+
 ## [2.25.3] - 2026-04-08
 
 ### Added

core/bin/pmxt-ensure-server

@@ -113,10 +113,23 @@ async function startServer() {
         serverCmd = localBinServer;
     }
 
+    // Open a log file for the sidecar so SDK consumers can call
+    // `pmxt.server.logs()` and see real output. Falls back to 'ignore' if the
+    // file cannot be opened (e.g. read-only home directory).
+    const logFile = path.join(os.homedir(), '.pmxt', 'server.log');
+    let stdio = 'ignore';
+    try {
+        fs.mkdirSync(path.dirname(logFile), { recursive: true });
+        const fd = fs.openSync(logFile, 'a');
+        stdio = ['ignore', fd, fd];
+    } catch (err) {
+        // Keep stdio: 'ignore' on failure - logging is best-effort.
+    }
+
     // Spawn server as detached process
     const serverProcess = spawn(serverCmd, args, {
         detached: true,
-        stdio: 'ignore',
+        stdio,
         env: process.env
     });
 

core/bin/pmxt-ensure-server.js

@@ -113,10 +113,23 @@ async function startServer() {
         serverCmd = localBinServer;
     }
 
+    // Open a log file for the sidecar so SDK consumers can call
+    // `pmxt.server.logs()` and see real output. Falls back to 'ignore' if the
+    // file cannot be opened (e.g. read-only home directory).
+    const logFile = path.join(os.homedir(), '.pmxt', 'server.log');
+    let stdio = 'ignore';
+    try {
+        fs.mkdirSync(path.dirname(logFile), { recursive: true });
+        const fd = fs.openSync(logFile, 'a');
+        stdio = ['ignore', fd, fd];
+    } catch (err) {
+        // Keep stdio: 'ignore' on failure - logging is best-effort.
+    }
+
     // Spawn server as detached process
     const serverProcess = spawn(serverCmd, args, {
         detached: true,
-        stdio: 'ignore',
+        stdio,
         env: process.env
     });
 

scripts/templates/api-reference.python.md.hbs

@@ -29,24 +29,74 @@ print(markets[0].title)
 
 ## Server Management
 
-The SDK provides global functions to manage the background sidecar server. This is useful for clearing state, resolving "port busy" errors, or ensuring a clean slate in interactive environments like Jupyter.
+The SDK exposes a `pmxt.server` namespace for managing the background sidecar server. Use these commands for clearing state, resolving "port busy" errors, inspecting server health, or tailing logs from interactive environments like Jupyter.
 
-### `stop_server`
+```python
+import pmxt
+
+pmxt.server.status()    # snapshot dict: running, pid, port, version, uptime_seconds, lock_file
+pmxt.server.health()    # bool - True if /health responds ok
+pmxt.server.start()     # idempotent - no-op if already running
+pmxt.server.stop()      # stop the sidecar and clean up the lock file
+pmxt.server.restart()   # stop and start the sidecar
+pmxt.server.logs(50)    # last N log lines from ~/.pmxt/server.log (default 50)
+```
+
+### `pmxt.server.status`
+
+Returns a fresh dict describing the sidecar state. Useful for diagnosing "is it running?" before issuing API calls.
+
+```python
+import pmxt
+info = pmxt.server.status()
+print(info["running"], info["pid"], info["port"], info["uptime_seconds"])
+```
+
+### `pmxt.server.health`
+
+Returns `True` if the sidecar's `/health` endpoint responds with status `ok`, otherwise `False`. Lighter than `status()` when you only need a boolean liveness check.
+
+```python
+import pmxt
+if not pmxt.server.health():
+    pmxt.server.restart()
+```
+
+### `pmxt.server.start`
+
+Idempotently start the sidecar. Returns immediately if a healthy server is already running. Use this when you want to fail fast on startup rather than letting the first API call lazily boot the server.
+
+```python
+import pmxt
+pmxt.server.start()
+```
+
+### `pmxt.server.stop`
+
+Stop the running sidecar and clean up its lock file.
+
+```python
+import pmxt
+pmxt.server.stop()
+```
+
+### `pmxt.server.restart`
 
-Stop the background PMXT sidecar server and clean up lock files.
+Stop the sidecar (if running) and start a fresh one. Equivalent to `stop()` followed by `start()`.
 
 ```python
 import pmxt
-pmxt.stop_server()
+pmxt.server.restart()
 ```
 
-### `restart_server`
+### `pmxt.server.logs`
 
-Restart the background PMXT sidecar server. Equivalent to calling `stop_server()` followed by a fresh start.
+Return the last `n` lines (default `50`) from the sidecar log file at `~/.pmxt/server.log`. Returns an empty list if no log file exists yet. Invaluable when the server is misbehaving and you need to see what it actually printed.
 
 ```python
 import pmxt
-pmxt.restart_server()
+for line in pmxt.server.logs(100):
+    print(line)
 ```
 
 ---

scripts/templates/api-reference.typescript.md.hbs

@@ -30,25 +30,76 @@ console.log(markets[0].title);
 
 ## Server Management
 
-The SDK provides global functions to manage the background sidecar server. This is useful for clearing state or
-resolving "port busy" errors.
+The SDK exposes a `pmxt.server` namespace for managing the background sidecar server. Use these commands for clearing state, resolving "port busy" errors, inspecting health, or tailing logs.
 
-### `stopServer`
+```typescript
+import pmxt from 'pmxtjs';
+
+await pmxt.server.status();    // snapshot: { running, pid, port, version, uptimeSeconds, lockFile }
+await pmxt.server.health();    // boolean - true if /health responds ok
+await pmxt.server.start();     // idempotent - no-op if already running
+await pmxt.server.stop();      // stop the sidecar and clean up the lock file
+await pmxt.server.restart();   // stop and start the sidecar
+pmxt.server.logs(50);          // last N log lines from ~/.pmxt/server.log (default 50)
+```
+
+### `pmxt.server.status`
+
+Returns a fresh object describing the sidecar state. Useful for diagnosing "is it running?" before issuing API calls.
+
+```typescript
+import pmxt from 'pmxtjs';
+const info = await pmxt.server.status();
+console.log(info.running, info.pid, info.port, info.uptimeSeconds);
+```
 
-Stop the background PMXT sidecar server and clean up lock files.
+### `pmxt.server.health`
+
+Returns `true` if the sidecar's `/health` endpoint responds with status `ok`, otherwise `false`. Lighter than `status()` when you only need a boolean liveness check.
 
 ```typescript
 import pmxt from 'pmxtjs';
-await pmxt.stopServer();
+if (!(await pmxt.server.health())) {
+  await pmxt.server.restart();
+}
 ```
 
-### `restartServer`
+### `pmxt.server.start`
 
-Restart the background PMXT sidecar server. Equivalent to calling `stopServer()` followed by a fresh start.
+Idempotently start the sidecar. Returns immediately if a healthy server is already running. Use this when you want to fail fast on startup rather than letting the first API call lazily boot the server.
 
 ```typescript
 import pmxt from 'pmxtjs';
-await pmxt.restartServer();
+await pmxt.server.start();
+```
+
+### `pmxt.server.stop`
+
+Stop the running sidecar and clean up its lock file.
+
+```typescript
+import pmxt from 'pmxtjs';
+await pmxt.server.stop();
+```
+
+### `pmxt.server.restart`
+
+Stop the sidecar (if running) and start a fresh one. Equivalent to `stop()` followed by `start()`.
+
+```typescript
+import pmxt from 'pmxtjs';
+await pmxt.server.restart();
+```
+
+### `pmxt.server.logs`
+
+Return the last `n` lines (default `50`) from the sidecar log file at `~/.pmxt/server.log`. Returns an empty array if no log file exists yet. Invaluable when the server is misbehaving and you need to see what it actually printed.
+
+```typescript
+import pmxt from 'pmxtjs';
+for (const line of pmxt.server.logs(100)) {
+  console.log(line);
+}
 ```
 
 ---

sdks/python/API_REFERENCE.md

@@ -29,24 +29,74 @@ print(markets[0].title)
 
 ## Server Management
 
-The SDK provides global functions to manage the background sidecar server. This is useful for clearing state, resolving "port busy" errors, or ensuring a clean slate in interactive environments like Jupyter.
+The SDK exposes a `pmxt.server` namespace for managing the background sidecar server. Use these commands for clearing state, resolving "port busy" errors, inspecting server health, or tailing logs from interactive environments like Jupyter.
 
-### `stop_server`
+```python
+import pmxt
+
+pmxt.server.status()    # snapshot dict: running, pid, port, version, uptime_seconds, lock_file
+pmxt.server.health()    # bool - True if /health responds ok
+pmxt.server.start()     # idempotent - no-op if already running
+pmxt.server.stop()      # stop the sidecar and clean up the lock file
+pmxt.server.restart()   # stop and start the sidecar
+pmxt.server.logs(50)    # last N log lines from ~/.pmxt/server.log (default 50)
+```
+
+### `pmxt.server.status`
+
+Returns a fresh dict describing the sidecar state. Useful for diagnosing "is it running?" before issuing API calls.
+
+```python
+import pmxt
+info = pmxt.server.status()
+print(info["running"], info["pid"], info["port"], info["uptime_seconds"])
+```
 
-Stop the background PMXT sidecar server and clean up lock files.
+### `pmxt.server.health`
+
+Returns `True` if the sidecar's `/health` endpoint responds with status `ok`, otherwise `False`. Lighter than `status()` when you only need a boolean liveness check.
 
 ```python
 import pmxt
-pmxt.stop_server()
+if not pmxt.server.health():
+    pmxt.server.restart()
 ```
 
-### `restart_server`
+### `pmxt.server.start`
 
-Restart the background PMXT sidecar server. Equivalent to calling `stop_server()` followed by a fresh start.
+Idempotently start the sidecar. Returns immediately if a healthy server is already running. Use this when you want to fail fast on startup rather than letting the first API call lazily boot the server.
 
 ```python
 import pmxt
-pmxt.restart_server()
+pmxt.server.start()
+```
+
+### `pmxt.server.stop`
+
+Stop the running sidecar and clean up its lock file.
+
+```python
+import pmxt
+pmxt.server.stop()
+```
+
+### `pmxt.server.restart`
+
+Stop the sidecar (if running) and start a fresh one. Equivalent to `stop()` followed by `start()`.
+
+```python
+import pmxt
+pmxt.server.restart()
+```
+
+### `pmxt.server.logs`
+
+Return the last `n` lines (default `50`) from the sidecar log file at `~/.pmxt/server.log`. Returns an empty list if no log file exists yet. Invaluable when the server is misbehaving and you need to see what it actually printed.
+
+```python
+import pmxt
+for line in pmxt.server.logs(100):
+    print(line)
 ```
 
 ---
@@ -1144,6 +1194,7 @@ class UnifiedMarket:
 market_id: str # The unique identifier for this market
 title: str # 
 description: str # 
+slug: str # 
 outcomes: List[MarketOutcome] # 
 event_id: str # Link to parent event
 resolution_date: str # 
@@ -1155,6 +1206,9 @@ url: str #
 image: str # 
 category: str # 
 tags: List[string] # 
+tick_size: float # Minimum price increment (e.g., 0.01, 0.001)
+status: str # Venue-native lifecycle status (e.g. 'active', 'closed', 'archived').
+contract_address: str # On-chain contract / condition identifier where applicable (Polymarket conditionId, etc.).
 yes: MarketOutcome # 
 no: MarketOutcome # 
 up: MarketOutcome # 
@@ -1190,6 +1244,8 @@ title: str #
 description: str # 
 slug: str # 
 markets: List[UnifiedMarket] # 
+volume24h: float # 
+volume: float # Total / Lifetime volume (sum across markets; undefined if no market provides it)
 url: str # 
 image: str # 
 category: str # 
@@ -1491,6 +1547,8 @@ type: str #
 amount: float # 
 price: float # 
 fee: float # 
+tick_size: float # Optional override for Limitless/Polymarket
+neg_risk: bool # Optional override to skip neg-risk lookup (Polymarket)
 ```
 
 ---