pmxtjs 2.25.3 → 2.26.0

package/dist/esm/index.d.ts

@@ -28,6 +28,32 @@ export type * from "./pmxt/models.js";
 export * from "./pmxt/errors.js";
 declare function stopServer(): Promise<void>;
 declare function restartServer(): Promise<void>;
+/**
+ * Namespaced server management API.
+ *
+ * Available commands:
+ *  - status()  Structured snapshot of the sidecar (running, pid, port, version, uptime)
+ *  - health()  True if the server responds to /health, false otherwise
+ *  - start()   Idempotently start the sidecar (no-op if already running)
+ *  - stop()    Stop the sidecar and clean up the lock file
+ *  - restart() Stop and start the sidecar
+ *  - logs(n)   Return the last n log lines from the sidecar log file
+ */
+export declare const server: {
+    readonly status: () => Promise<{
+        running: boolean;
+        pid: number | null;
+        port: number | null;
+        version: string | null;
+        uptimeSeconds: number | null;
+        lockFile: string;
+    }>;
+    readonly health: () => Promise<boolean>;
+    readonly start: () => Promise<void>;
+    readonly stop: () => Promise<void>;
+    readonly restart: () => Promise<void>;
+    readonly logs: (n?: number) => string[];
+};
 declare const pmxt: {
     fromServerError(errorData: any): errors.PmxtError;
     PmxtError: typeof errors.PmxtError;
@@ -58,6 +84,21 @@ declare const pmxt: {
     Smarkets: typeof Smarkets;
     PolymarketUS: typeof PolymarketUS;
     ServerManager: typeof ServerManager;
+    server: {
+        readonly status: () => Promise<{
+            running: boolean;
+            pid: number | null;
+            port: number | null;
+            version: string | null;
+            uptimeSeconds: number | null;
+            lockFile: string;
+        }>;
+        readonly health: () => Promise<boolean>;
+        readonly start: () => Promise<void>;
+        readonly stop: () => Promise<void>;
+        readonly restart: () => Promise<void>;
+        readonly logs: (n?: number) => string[];
+    };
     stopServer: typeof stopServer;
     restartServer: typeof restartServer;
 };

package/dist/esm/index.js

@@ -26,12 +26,34 @@ export { ServerManager } from "./pmxt/server-manager.js";
 export { MarketList } from "./pmxt/models.js";
 export * from "./pmxt/errors.js";
 const defaultManager = new ServerManager();
+// Flat aliases for the namespaced server commands. Kept as permanent,
+// fully-supported shorthand — `pmxt.server.stop()` and `pmxt.stopServer()`
+// are equivalent and both are first-class API.
 async function stopServer() {
     await defaultManager.stop();
 }
 async function restartServer() {
     await defaultManager.restart();
 }
+/**
+ * Namespaced server management API.
+ *
+ * Available commands:
+ *  - status()  Structured snapshot of the sidecar (running, pid, port, version, uptime)
+ *  - health()  True if the server responds to /health, false otherwise
+ *  - start()   Idempotently start the sidecar (no-op if already running)
+ *  - stop()    Stop the sidecar and clean up the lock file
+ *  - restart() Stop and start the sidecar
+ *  - logs(n)   Return the last n log lines from the sidecar log file
+ */
+export const server = {
+    status: () => defaultManager.status(),
+    health: () => defaultManager.health(),
+    start: () => defaultManager.start(),
+    stop: () => defaultManager.stop(),
+    restart: () => defaultManager.restart(),
+    logs: (n = 50) => defaultManager.logs(n),
+};
 const pmxt = {
     Exchange,
     Polymarket,
@@ -46,6 +68,7 @@ const pmxt = {
     Smarkets,
     PolymarketUS,
     ServerManager,
+    server,
     stopServer,
     restartServer,
     ...models,

package/dist/esm/pmxt/server-manager.d.ts

@@ -15,6 +15,7 @@ export declare class ServerManager {
     private api;
     private lockPath;
     private static readonly DEFAULT_PORT;
+    private static ensurePromise;
     constructor(options?: ServerManagerOptions);
     /**
      * Read server information from lock file.
@@ -43,8 +44,13 @@ export declare class ServerManager {
     private waitForServer;
     /**
      * Ensure the server is running, starting it if necessary.
+     *
+     * Concurrent calls across all ServerManager instances in the process
+     * are coalesced onto a single in-flight promise. See the comment on
+     * `ServerManager.ensurePromise` for why this matters.
      */
     ensureServerRunning(): Promise<void>;
+    private doEnsureServerRunning;
     private isVersionMismatch;
     /**
      * Stop the currently running server.
@@ -54,5 +60,36 @@ export declare class ServerManager {
      * Restart the server.
      */
     restart(): Promise<void>;
+    /**
+     * Start the server if it is not already running.
+     *
+     * Idempotent: if the server is already running and healthy this returns
+     * immediately without restarting.
+     */
+    start(): Promise<void>;
+    /**
+     * Get a structured snapshot of the sidecar server state.
+     *
+     * Returns a fresh object on every call (no shared mutable state).
+     */
+    status(): Promise<{
+        running: boolean;
+        pid: number | null;
+        port: number | null;
+        version: string | null;
+        uptimeSeconds: number | null;
+        lockFile: string;
+    }>;
+    /**
+     * Check whether the server's /health endpoint is currently responsive.
+     */
+    health(): Promise<boolean>;
+    /**
+     * Return the last `n` lines from the sidecar server log file.
+     *
+     * The launcher writes server stdout/stderr to ~/.pmxt/server.log.
+     * Returns an empty array if no log file is present.
+     */
+    logs(n?: number): string[];
     private killOldServer;
 }

package/dist/esm/pmxt/server-manager.js

@@ -14,6 +14,28 @@ export class ServerManager {
     api;
     lockPath;
     static DEFAULT_PORT = 3847;
+    // Process-wide coalescing of concurrent ensureServerRunning() calls.
+    //
+    // Each `Exchange` instance constructs its own ServerManager and each one
+    // kicks off ensureServerRunning() from its constructor. Without
+    // coalescing, N Exchange instances created in parallel all see "no
+    // server running", all spawn their own sidecar via pmxt-ensure-server,
+    // and the lock file ends up pointing at whichever spawn wrote last. Each
+    // Exchange instance has already captured its own basePath at
+    // construction time, so most of them end up talking to a sidecar whose
+    // access token does NOT match the token they later read from the lock
+    // file — every request returns 401 Unauthorized.
+    //
+    // The fix is process-wide: when a ensureServerRunning call is in
+    // flight, all subsequent callers await the same promise. After the
+    // in-flight call settles (success OR failure) the cache is cleared so
+    // later callers can re-check the sidecar state (e.g. if it was killed
+    // by the user between ticks).
+    //
+    // This is static on purpose — all ServerManager instances in the
+    // process share the same sidecar and the same lock file, so they must
+    // share the same in-flight promise.
+    static ensurePromise = null;
     constructor(options = {}) {
         this.baseUrl = options.baseUrl || `http://localhost:${ServerManager.DEFAULT_PORT}`;
         this.maxRetries = options.maxRetries || 30;
@@ -101,8 +123,21 @@ export class ServerManager {
     }
     /**
      * Ensure the server is running, starting it if necessary.
+     *
+     * Concurrent calls across all ServerManager instances in the process
+     * are coalesced onto a single in-flight promise. See the comment on
+     * `ServerManager.ensurePromise` for why this matters.
      */
     async ensureServerRunning() {
+        if (ServerManager.ensurePromise) {
+            return ServerManager.ensurePromise;
+        }
+        ServerManager.ensurePromise = this.doEnsureServerRunning().finally(() => {
+            ServerManager.ensurePromise = null;
+        });
+        return ServerManager.ensurePromise;
+    }
+    async doEnsureServerRunning() {
         // Check for force restart
         if (process.env.PMXT_ALWAYS_RESTART === '1') {
             await this.killOldServer();
@@ -201,6 +236,70 @@ export class ServerManager {
         await this.stop();
         await this.ensureServerRunning();
     }
+    /**
+     * Start the server if it is not already running.
+     *
+     * Idempotent: if the server is already running and healthy this returns
+     * immediately without restarting.
+     */
+    async start() {
+        await this.ensureServerRunning();
+    }
+    /**
+     * Get a structured snapshot of the sidecar server state.
+     *
+     * Returns a fresh object on every call (no shared mutable state).
+     */
+    async status() {
+        const info = this.getServerInfo();
+        const running = await this.isServerRunning();
+        let uptimeSeconds = null;
+        if (info && typeof info.timestamp === "number") {
+            const nowSeconds = Date.now() / 1000;
+            const tsSeconds = info.timestamp > 1e12 ? info.timestamp / 1000 : info.timestamp;
+            const delta = nowSeconds - tsSeconds;
+            if (delta >= 0)
+                uptimeSeconds = delta;
+        }
+        return {
+            running,
+            pid: info?.pid ?? null,
+            port: info?.port ?? null,
+            version: info?.version ?? null,
+            uptimeSeconds,
+            lockFile: this.lockPath,
+        };
+    }
+    /**
+     * Check whether the server's /health endpoint is currently responsive.
+     */
+    async health() {
+        return this.isServerRunning();
+    }
+    /**
+     * Return the last `n` lines from the sidecar server log file.
+     *
+     * The launcher writes server stdout/stderr to ~/.pmxt/server.log.
+     * Returns an empty array if no log file is present.
+     */
+    logs(n = 50) {
+        if (n <= 0)
+            return [];
+        const logPath = join(dirname(this.lockPath), "server.log");
+        try {
+            if (!existsSync(logPath))
+                return [];
+            const content = readFileSync(logPath, "utf-8");
+            const lines = content.split(/\r?\n/);
+            // split on a trailing newline produces an empty final element; drop it
+            if (lines.length > 0 && lines[lines.length - 1] === "")
+                lines.pop();
+            return lines.length > n ? lines.slice(lines.length - n) : lines;
+        }
+        catch {
+            return [];
+        }
+    }
     async killOldServer() {
         const info = this.getServerInfo();
         if (info && info.pid) {

package/dist/index.d.ts

@@ -28,6 +28,32 @@ export type * from "./pmxt/models.js";
 export * from "./pmxt/errors.js";
 declare function stopServer(): Promise<void>;
 declare function restartServer(): Promise<void>;
+/**
+ * Namespaced server management API.
+ *
+ * Available commands:
+ *  - status()  Structured snapshot of the sidecar (running, pid, port, version, uptime)
+ *  - health()  True if the server responds to /health, false otherwise
+ *  - start()   Idempotently start the sidecar (no-op if already running)
+ *  - stop()    Stop the sidecar and clean up the lock file
+ *  - restart() Stop and start the sidecar
+ *  - logs(n)   Return the last n log lines from the sidecar log file
+ */
+export declare const server: {
+    readonly status: () => Promise<{
+        running: boolean;
+        pid: number | null;
+        port: number | null;
+        version: string | null;
+        uptimeSeconds: number | null;
+        lockFile: string;
+    }>;
+    readonly health: () => Promise<boolean>;
+    readonly start: () => Promise<void>;
+    readonly stop: () => Promise<void>;
+    readonly restart: () => Promise<void>;
+    readonly logs: (n?: number) => string[];
+};
 declare const pmxt: {
     fromServerError(errorData: any): errors.PmxtError;
     PmxtError: typeof errors.PmxtError;
@@ -58,6 +84,21 @@ declare const pmxt: {
     Smarkets: typeof Smarkets;
     PolymarketUS: typeof PolymarketUS;
     ServerManager: typeof ServerManager;
+    server: {
+        readonly status: () => Promise<{
+            running: boolean;
+            pid: number | null;
+            port: number | null;
+            version: string | null;
+            uptimeSeconds: number | null;
+            lockFile: string;
+        }>;
+        readonly health: () => Promise<boolean>;
+        readonly start: () => Promise<void>;
+        readonly stop: () => Promise<void>;
+        readonly restart: () => Promise<void>;
+        readonly logs: (n?: number) => string[];
+    };
     stopServer: typeof stopServer;
     restartServer: typeof restartServer;
 };

package/dist/index.js

@@ -55,7 +55,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.MarketList = exports.ServerManager = exports.PolymarketUS = exports.Smarkets = exports.Metaculus = exports.Opinion = exports.Baozi = exports.Probable = exports.Myriad = exports.Limitless = exports.KalshiDemo = exports.Kalshi = exports.Polymarket = exports.Exchange = void 0;
+exports.server = exports.MarketList = exports.ServerManager = exports.PolymarketUS = exports.Smarkets = exports.Metaculus = exports.Opinion = exports.Baozi = exports.Probable = exports.Myriad = exports.Limitless = exports.KalshiDemo = exports.Kalshi = exports.Polymarket = exports.Exchange = void 0;
 const client_js_1 = require("./pmxt/client.js");
 const server_manager_js_1 = require("./pmxt/server-manager.js");
 const models = __importStar(require("./pmxt/models.js"));
@@ -79,12 +79,34 @@ var models_js_1 = require("./pmxt/models.js");
 Object.defineProperty(exports, "MarketList", { enumerable: true, get: function () { return models_js_1.MarketList; } });
 __exportStar(require("./pmxt/errors.js"), exports);
 const defaultManager = new server_manager_js_1.ServerManager();
+// Flat aliases for the namespaced server commands. Kept as permanent,
+// fully-supported shorthand — `pmxt.server.stop()` and `pmxt.stopServer()`
+// are equivalent and both are first-class API.
 async function stopServer() {
     await defaultManager.stop();
 }
 async function restartServer() {
     await defaultManager.restart();
 }
+/**
+ * Namespaced server management API.
+ *
+ * Available commands:
+ *  - status()  Structured snapshot of the sidecar (running, pid, port, version, uptime)
+ *  - health()  True if the server responds to /health, false otherwise
+ *  - start()   Idempotently start the sidecar (no-op if already running)
+ *  - stop()    Stop the sidecar and clean up the lock file
+ *  - restart() Stop and start the sidecar
+ *  - logs(n)   Return the last n log lines from the sidecar log file
+ */
+exports.server = {
+    status: () => defaultManager.status(),
+    health: () => defaultManager.health(),
+    start: () => defaultManager.start(),
+    stop: () => defaultManager.stop(),
+    restart: () => defaultManager.restart(),
+    logs: (n = 50) => defaultManager.logs(n),
+};
 const pmxt = {
     Exchange: client_js_1.Exchange,
     Polymarket: client_js_1.Polymarket,
@@ -99,6 +121,7 @@ const pmxt = {
     Smarkets: client_js_1.Smarkets,
     PolymarketUS: client_js_1.PolymarketUS,
     ServerManager: server_manager_js_1.ServerManager,
+    server: exports.server,
     stopServer,
     restartServer,
     ...models,

package/dist/pmxt/server-manager.d.ts

@@ -15,6 +15,7 @@ export declare class ServerManager {
     private api;
     private lockPath;
     private static readonly DEFAULT_PORT;
+    private static ensurePromise;
     constructor(options?: ServerManagerOptions);
     /**
      * Read server information from lock file.
@@ -43,8 +44,13 @@ export declare class ServerManager {
     private waitForServer;
     /**
      * Ensure the server is running, starting it if necessary.
+     *
+     * Concurrent calls across all ServerManager instances in the process
+     * are coalesced onto a single in-flight promise. See the comment on
+     * `ServerManager.ensurePromise` for why this matters.
      */
     ensureServerRunning(): Promise<void>;
+    private doEnsureServerRunning;
     private isVersionMismatch;
     /**
      * Stop the currently running server.
@@ -54,5 +60,36 @@ export declare class ServerManager {
      * Restart the server.
      */
     restart(): Promise<void>;
+    /**
+     * Start the server if it is not already running.
+     *
+     * Idempotent: if the server is already running and healthy this returns
+     * immediately without restarting.
+     */
+    start(): Promise<void>;
+    /**
+     * Get a structured snapshot of the sidecar server state.
+     *
+     * Returns a fresh object on every call (no shared mutable state).
+     */
+    status(): Promise<{
+        running: boolean;
+        pid: number | null;
+        port: number | null;
+        version: string | null;
+        uptimeSeconds: number | null;
+        lockFile: string;
+    }>;
+    /**
+     * Check whether the server's /health endpoint is currently responsive.
+     */
+    health(): Promise<boolean>;
+    /**
+     * Return the last `n` lines from the sidecar server log file.
+     *
+     * The launcher writes server stdout/stderr to ~/.pmxt/server.log.
+     * Returns an empty array if no log file is present.
+     */
+    logs(n?: number): string[];
     private killOldServer;
 }

package/dist/pmxt/server-manager.js

@@ -50,6 +50,28 @@ class ServerManager {
     api;
     lockPath;
     static DEFAULT_PORT = 3847;
+    // Process-wide coalescing of concurrent ensureServerRunning() calls.
+    //
+    // Each `Exchange` instance constructs its own ServerManager and each one
+    // kicks off ensureServerRunning() from its constructor. Without
+    // coalescing, N Exchange instances created in parallel all see "no
+    // server running", all spawn their own sidecar via pmxt-ensure-server,
+    // and the lock file ends up pointing at whichever spawn wrote last. Each
+    // Exchange instance has already captured its own basePath at
+    // construction time, so most of them end up talking to a sidecar whose
+    // access token does NOT match the token they later read from the lock
+    // file — every request returns 401 Unauthorized.
+    //
+    // The fix is process-wide: when a ensureServerRunning call is in
+    // flight, all subsequent callers await the same promise. After the
+    // in-flight call settles (success OR failure) the cache is cleared so
+    // later callers can re-check the sidecar state (e.g. if it was killed
+    // by the user between ticks).
+    //
+    // This is static on purpose — all ServerManager instances in the
+    // process share the same sidecar and the same lock file, so they must
+    // share the same in-flight promise.
+    static ensurePromise = null;
     constructor(options = {}) {
         this.baseUrl = options.baseUrl || `http://localhost:${ServerManager.DEFAULT_PORT}`;
         this.maxRetries = options.maxRetries || 30;
@@ -137,8 +159,21 @@ class ServerManager {
     }
     /**
      * Ensure the server is running, starting it if necessary.
+     *
+     * Concurrent calls across all ServerManager instances in the process
+     * are coalesced onto a single in-flight promise. See the comment on
+     * `ServerManager.ensurePromise` for why this matters.
      */
     async ensureServerRunning() {
+        if (ServerManager.ensurePromise) {
+            return ServerManager.ensurePromise;
+        }
+        ServerManager.ensurePromise = this.doEnsureServerRunning().finally(() => {
+            ServerManager.ensurePromise = null;
+        });
+        return ServerManager.ensurePromise;
+    }
+    async doEnsureServerRunning() {
         // Check for force restart
         if (process.env.PMXT_ALWAYS_RESTART === '1') {
             await this.killOldServer();
@@ -237,6 +272,70 @@ class ServerManager {
         await this.stop();
         await this.ensureServerRunning();
     }
+    /**
+     * Start the server if it is not already running.
+     *
+     * Idempotent: if the server is already running and healthy this returns
+     * immediately without restarting.
+     */
+    async start() {
+        await this.ensureServerRunning();
+    }
+    /**
+     * Get a structured snapshot of the sidecar server state.
+     *
+     * Returns a fresh object on every call (no shared mutable state).
+     */
+    async status() {
+        const info = this.getServerInfo();
+        const running = await this.isServerRunning();
+        let uptimeSeconds = null;
+        if (info && typeof info.timestamp === "number") {
+            const nowSeconds = Date.now() / 1000;
+            const tsSeconds = info.timestamp > 1e12 ? info.timestamp / 1000 : info.timestamp;
+            const delta = nowSeconds - tsSeconds;
+            if (delta >= 0)
+                uptimeSeconds = delta;
+        }
+        return {
+            running,
+            pid: info?.pid ?? null,
+            port: info?.port ?? null,
+            version: info?.version ?? null,
+            uptimeSeconds,
+            lockFile: this.lockPath,
+        };
+    }
+    /**
+     * Check whether the server's /health endpoint is currently responsive.
+     */
+    async health() {
+        return this.isServerRunning();
+    }
+    /**
+     * Return the last `n` lines from the sidecar server log file.
+     *
+     * The launcher writes server stdout/stderr to ~/.pmxt/server.log.
+     * Returns an empty array if no log file is present.
+     */
+    logs(n = 50) {
+        if (n <= 0)
+            return [];
+        const logPath = (0, path_1.join)((0, path_1.dirname)(this.lockPath), "server.log");
+        try {
+            if (!(0, fs_1.existsSync)(logPath))
+                return [];
+            const content = (0, fs_1.readFileSync)(logPath, "utf-8");
+            const lines = content.split(/\r?\n/);
+            // split on a trailing newline produces an empty final element; drop it
+            if (lines.length > 0 && lines[lines.length - 1] === "")
+                lines.pop();
+            return lines.length > n ? lines.slice(lines.length - n) : lines;
+        }
+        catch {
+            return [];
+        }
+    }
     async killOldServer() {
         const info = this.getServerInfo();
         if (info && info.pid) {

package/generated/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pmxtjs",
-  "version": "2.25.3",
+  "version": "2.26.0",
   "description": "OpenAPI client for pmxtjs",
   "author": "OpenAPI-Generator",
   "repository": {

package/index.ts

@@ -33,6 +33,9 @@ export * from "./pmxt/errors.js";
 
 const defaultManager = new ServerManager();
 
+// Flat aliases for the namespaced server commands. Kept as permanent,
+// fully-supported shorthand — `pmxt.server.stop()` and `pmxt.stopServer()`
+// are equivalent and both are first-class API.
 async function stopServer(): Promise<void> {
     await defaultManager.stop();
 }
@@ -41,6 +44,26 @@ async function restartServer(): Promise<void> {
     await defaultManager.restart();
 }
 
+/**
+ * Namespaced server management API.
+ *
+ * Available commands:
+ *  - status()  Structured snapshot of the sidecar (running, pid, port, version, uptime)
+ *  - health()  True if the server responds to /health, false otherwise
+ *  - start()   Idempotently start the sidecar (no-op if already running)
+ *  - stop()    Stop the sidecar and clean up the lock file
+ *  - restart() Stop and start the sidecar
+ *  - logs(n)   Return the last n log lines from the sidecar log file
+ */
+export const server = {
+    status: () => defaultManager.status(),
+    health: () => defaultManager.health(),
+    start: () => defaultManager.start(),
+    stop: () => defaultManager.stop(),
+    restart: () => defaultManager.restart(),
+    logs: (n: number = 50) => defaultManager.logs(n),
+} as const;
+
 const pmxt = {
     Exchange,
     Polymarket,
@@ -55,6 +78,7 @@ const pmxt = {
     Smarkets,
     PolymarketUS,
     ServerManager,
+    server,
     stopServer,
     restartServer,
     ...models,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pmxtjs",
-  "version": "2.25.3",
+  "version": "2.26.0",
   "description": "Unified prediction market data API - The ccxt for prediction markets",
   "author": "PMXT Contributors",
   "repository": {
@@ -43,7 +43,7 @@
     "unified"
   ],
   "dependencies": {
-    "pmxt-core": "2.25.3"
+    "pmxt-core": "2.26.0"
   },
   "devDependencies": {
     "@types/jest": "^30.0.0",

package/pmxt/server-manager.ts

@@ -31,6 +31,29 @@ export class ServerManager {
     private lockPath: string;
     private static readonly DEFAULT_PORT = 3847;
 
+    // Process-wide coalescing of concurrent ensureServerRunning() calls.
+    //
+    // Each `Exchange` instance constructs its own ServerManager and each one
+    // kicks off ensureServerRunning() from its constructor. Without
+    // coalescing, N Exchange instances created in parallel all see "no
+    // server running", all spawn their own sidecar via pmxt-ensure-server,
+    // and the lock file ends up pointing at whichever spawn wrote last. Each
+    // Exchange instance has already captured its own basePath at
+    // construction time, so most of them end up talking to a sidecar whose
+    // access token does NOT match the token they later read from the lock
+    // file — every request returns 401 Unauthorized.
+    //
+    // The fix is process-wide: when a ensureServerRunning call is in
+    // flight, all subsequent callers await the same promise. After the
+    // in-flight call settles (success OR failure) the cache is cleared so
+    // later callers can re-check the sidecar state (e.g. if it was killed
+    // by the user between ticks).
+    //
+    // This is static on purpose — all ServerManager instances in the
+    // process share the same sidecar and the same lock file, so they must
+    // share the same in-flight promise.
+    private static ensurePromise: Promise<void> | null = null;
+
     constructor(options: ServerManagerOptions = {}) {
         this.baseUrl = options.baseUrl || `http://localhost:${ServerManager.DEFAULT_PORT}`;
         this.maxRetries = options.maxRetries || 30;
@@ -124,8 +147,22 @@ export class ServerManager {
 
     /**
      * Ensure the server is running, starting it if necessary.
+     *
+     * Concurrent calls across all ServerManager instances in the process
+     * are coalesced onto a single in-flight promise. See the comment on
+     * `ServerManager.ensurePromise` for why this matters.
      */
     async ensureServerRunning(): Promise<void> {
+        if (ServerManager.ensurePromise) {
+            return ServerManager.ensurePromise;
+        }
+        ServerManager.ensurePromise = this.doEnsureServerRunning().finally(() => {
+            ServerManager.ensurePromise = null;
+        });
+        return ServerManager.ensurePromise;
+    }
+
+    private async doEnsureServerRunning(): Promise<void> {
         // Check for force restart
         if (process.env.PMXT_ALWAYS_RESTART === '1') {
             await this.killOldServer();
@@ -235,6 +272,78 @@ export class ServerManager {
         await this.ensureServerRunning();
     }
 
+    /**
+     * Start the server if it is not already running.
+     *
+     * Idempotent: if the server is already running and healthy this returns
+     * immediately without restarting.
+     */
+    async start(): Promise<void> {
+        await this.ensureServerRunning();
+    }
+
+    /**
+     * Get a structured snapshot of the sidecar server state.
+     *
+     * Returns a fresh object on every call (no shared mutable state).
+     */
+    async status(): Promise<{
+        running: boolean;
+        pid: number | null;
+        port: number | null;
+        version: string | null;
+        uptimeSeconds: number | null;
+        lockFile: string;
+    }> {
+        const info = this.getServerInfo();
+        const running = await this.isServerRunning();
+
+        let uptimeSeconds: number | null = null;
+        if (info && typeof info.timestamp === "number") {
+            const nowSeconds = Date.now() / 1000;
+            const tsSeconds = info.timestamp > 1e12 ? info.timestamp / 1000 : info.timestamp;
+            const delta = nowSeconds - tsSeconds;
+            if (delta >= 0) uptimeSeconds = delta;
+        }
+
+        return {
+            running,
+            pid: info?.pid ?? null,
+            port: info?.port ?? null,
+            version: info?.version ?? null,
+            uptimeSeconds,
+            lockFile: this.lockPath,
+        };
+    }
+
+    /**
+     * Check whether the server's /health endpoint is currently responsive.
+     */
+    async health(): Promise<boolean> {
+        return this.isServerRunning();
+    }
+
+    /**
+     * Return the last `n` lines from the sidecar server log file.
+     *
+     * The launcher writes server stdout/stderr to ~/.pmxt/server.log.
+     * Returns an empty array if no log file is present.
+     */
+    logs(n: number = 50): string[] {
+        if (n <= 0) return [];
+        const logPath = join(dirname(this.lockPath), "server.log");
+        try {
+            if (!existsSync(logPath)) return [];
+            const content = readFileSync(logPath, "utf-8");
+            const lines = content.split(/\r?\n/);
+            // split on a trailing newline produces an empty final element; drop it
+            if (lines.length > 0 && lines[lines.length - 1] === "") lines.pop();
+            return lines.length > n ? lines.slice(lines.length - n) : lines;
+        } catch {
+            return [];
+        }
+    }
+
     private async killOldServer(): Promise<void> {
         const info = this.getServerInfo();
         if (info && info.pid) {