commandmate 0.42.2 → 0.44.0

package/dist/cli/utils/daemon.d.ts

@@ -6,6 +6,12 @@
  */
 import { DaemonStatus, StartOptions } from '../types';
 import { ServerEnv } from './server-url';
+/** How long stop() waits for the server's process group after SIGTERM before escalating. */
+export declare const STOP_GRACE_TIMEOUT_MS = 10000;
+/** How long stop() waits for the process group after SIGKILL. */
+export declare const STOP_KILL_TIMEOUT_MS = 3000;
+/** How long stop() waits for the recorded port to be released once the group is gone. */
+export declare const PORT_RELEASE_TIMEOUT_MS = 3000;
 /**
  * Daemon manager for background server process
  */
@@ -35,12 +41,43 @@ export declare class DaemonManager {
      * @throws Error if already running
      */
     start(options: StartOptions): Promise<number>;
+    /** Throws when the recorded server is running, or an earlier server's group lives on. */
+    private assertNotRunning;
+    /** Builds the child process env from process.env, .env and the start options. */
+    private buildChildEnv;
+    /** Decides bind address, port and protocol, warning when exposed without protection. */
+    private resolveEndpoint;
+    /** Throws when something else already answers on the port the server would bind. */
+    private assertPortFree;
+    /** Persists the DaemonState; kills the spawned child and throws when the write fails. */
+    private recordState;
     /**
      * Stop daemon process
+     *
+     * Issue #3087: signals the daemon's whole process group, waits for every member to exit
+     * (escalating to SIGKILL after {@link STOP_GRACE_TIMEOUT_MS}), and then requires the recorded
+     * port to be free. "Stopped" is reported only when both hold. A recorded leader that already
+     * exited while its group lives on (the orphaned server of #3087) is stopped the same way.
+     *
      * @param force Use SIGKILL instead of SIGTERM
-     * @returns true if stopped successfully, false if not running
+     * @returns true if stopped (or the PID file was stale), false if not running or not stopped
      */
     stop(force?: boolean): Promise<boolean>;
+    /**
+     * Signal the daemon's process group and wait until no member is left.
+     *
+     * @returns true once the group is gone, false if it outlived SIGKILL
+     */
+    private terminateGroup;
+    /**
+     * Issue #3087: confirm the port the server was started on is free again.
+     *
+     * A state file from before #1354 records no port; re-deriving one from a .env that may have
+     * changed since could blame an unrelated listener, so that legacy case is not checked.
+     *
+     * @returns true when the port is free (or unknown), false if something still listens on it
+     */
+    private waitForPortRelease;
     /**
      * Get daemon status
      * @returns Status object or null if no PID file
@@ -51,7 +88,10 @@ export declare class DaemonManager {
      */
     isRunning(): Promise<boolean>;
     /**
-     * Wait for process to exit
+     * Wait until neither the recorded PID nor any member of its process group is alive
+     * (Issue #3087: the group, because the server outlives npm).
+     *
+     * @returns true if everything exited within the timeout
      */
     private waitForExit;
 }

package/dist/cli/utils/daemon.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"daemon.d.ts","sourceRoot":"","sources":["../../../src/cli/utils/daemon.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAOtD,OAAO,EAA2C,SAAS,EAAE,MAAM,cAAc,CAAC;AAElF;;GAEG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,UAAU,CAAa;IAC/B,OAAO,CAAC,MAAM,CAAY;IAC1B,OAAO,CAAC,OAAO,CAAC,CAAS;IACzB,OAAO,CAAC,YAAY,CAAC,CAAY;IAEjC;;;;OAIG;gBACS,WAAW,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM;IAMjD;;;;;;OAMG;IACH,eAAe,IAAI,SAAS;IAK5B;;;;;OAKG;IACG,KAAK,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,MAAM,CAAC;IA+GnD;;;;OAIG;IACG,IAAI,CAAC,KAAK,GAAE,OAAe,GAAG,OAAO,CAAC,OAAO,CAAC;IA8BpD;;;OAGG;IACG,SAAS,IAAI,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC;IAmD/C;;OAEG;IACG,SAAS,IAAI,OAAO,CAAC,OAAO,CAAC;IAInC;;OAEG;YACW,WAAW;CAiB1B"}
+{"version":3,"file":"daemon.d.ts","sourceRoot":"","sources":["../../../src/cli/utils/daemon.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAOtD,OAAO,EAA2C,SAAS,EAAE,MAAM,cAAc,CAAC;AASlF,4FAA4F;AAC5F,eAAO,MAAM,qBAAqB,QAAQ,CAAC;AAE3C,iEAAiE;AACjE,eAAO,MAAM,oBAAoB,OAAO,CAAC;AAEzC,yFAAyF;AACzF,eAAO,MAAM,uBAAuB,OAAO,CAAC;AAsE5C;;GAEG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,UAAU,CAAa;IAC/B,OAAO,CAAC,MAAM,CAAY;IAC1B,OAAO,CAAC,OAAO,CAAC,CAAS;IACzB,OAAO,CAAC,YAAY,CAAC,CAAY;IAEjC;;;;OAIG;gBACS,WAAW,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM;IAMjD;;;;;;OAMG;IACH,eAAe,IAAI,SAAS;IAK5B;;;;;OAKG;IACG,KAAK,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,MAAM,CAAC;IAoCnD,yFAAyF;IACzF,OAAO,CAAC,gBAAgB;IAiBxB,iFAAiF;IACjF,OAAO,CAAC,aAAa;IA2CrB,wFAAwF;IACxF,OAAO,CAAC,eAAe;IAoBvB,oFAAoF;YACtE,cAAc;IAgB5B,yFAAyF;IACzF,OAAO,CAAC,WAAW;IAkCnB;;;;;;;;;;OAUG;IACG,IAAI,CAAC,KAAK,GAAE,OAAe,GAAG,OAAO,CAAC,OAAO,CAAC;IAkDpD;;;;OAIG;YACW,cAAc;IAe5B;;;;;;;OAOG;YACW,kBAAkB;IAuBhC;;;OAGG;IACG,SAAS,IAAI,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC;IAmD/C;;OAEG;IACG,SAAS,IAAI,OAAO,CAAC,OAAO,CAAC;IAInC;;;;;OAKG;YACW,WAAW;CAc1B"}

package/dist/cli/utils/daemon.js

@@ -6,7 +6,7 @@
  * SF-1: SRP - Process management only (PID handling delegated to PidManager)
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DaemonManager = void 0;
+exports.DaemonManager = exports.PORT_RELEASE_TIMEOUT_MS = exports.STOP_KILL_TIMEOUT_MS = exports.STOP_GRACE_TIMEOUT_MS = void 0;
 const child_process_1 = require("child_process");
 const dotenv_1 = require("dotenv");
 const pid_manager_1 = require("./pid-manager");
@@ -16,6 +16,81 @@ const package_info_1 = require("./package-info");
 const security_messages_1 = require("../config/security-messages");
 const logger_1 = require("./logger");
 const server_url_1 = require("./server-url");
+const server_ready_1 = require("./server-ready");
+const process_inspect_1 = require("./process-inspect");
+/** How long stop() waits for the server's process group after SIGTERM before escalating. */
+exports.STOP_GRACE_TIMEOUT_MS = 10000;
+/** How long stop() waits for the process group after SIGKILL. */
+exports.STOP_KILL_TIMEOUT_MS = 3000;
+/** How long stop() waits for the recorded port to be released once the group is gone. */
+exports.PORT_RELEASE_TIMEOUT_MS = 3000;
+/**
+ * Whether a signal can be delivered to `target` (a PID, or a negated PGID).
+ * EPERM means it exists but belongs to someone else, which still counts as alive.
+ */
+function signalTargetExists(target) {
+    try {
+        process.kill(target, 0);
+        return true;
+    }
+    catch (err) {
+        return err.code === 'EPERM';
+    }
+}
+/**
+ * Issue #3087: whether the process is still running code. `kill(pid, 0)` also succeeds for a
+ * zombie, which without an init process (a container whose PID 1 never reaps) stays forever.
+ */
+function processAlive(pid) {
+    return signalTargetExists(pid) && !(0, process_inspect_1.isZombieProcess)(pid);
+}
+/**
+ * Issue #3087: whether any process of the group the daemon was spawned into is still alive.
+ *
+ * `start()` spawns with `detached: true`, so the recorded PID is a process-group leader and the
+ * server it launches (npm → node server.js) inherits that PGID. A PGID is not reused while any
+ * member is alive, so a live group with the recorded ID is ours even after the leader exited.
+ *
+ * A group whose members are all zombies has exited. Only Linux can tell (via /proc); elsewhere,
+ * or when /proc shows no member at all, the signal-based answer stands.
+ */
+function processGroupExists(pid) {
+    if (pid <= 1 || !signalTargetExists(-pid)) {
+        return false;
+    }
+    const states = (0, process_inspect_1.listProcessGroupStates)(pid);
+    return states === null || states.length === 0 || states.some((state) => !(0, process_inspect_1.isExitedState)(state));
+}
+/**
+ * Issue #3087: signal the whole process group, not just the recorded PID.
+ *
+ * The recorded PID is npm's, and npm does not reliably forward signals to the server it runs
+ * (observed on Linux), so `kill(pid)` alone left the server listening as an orphan. Falls back
+ * to the bare PID when no such group exists (e.g. a server that is not a group leader).
+ */
+function signalProcessGroup(pid, signal) {
+    // Never negate 0 or 1: kill(0) signals our own group and kill(-1) every process we may signal.
+    if (pid <= 1) {
+        throw new Error(`Refusing to signal invalid PID ${pid}`);
+    }
+    try {
+        process.kill(-pid, signal);
+        return;
+    }
+    catch (err) {
+        if (err.code !== 'ESRCH') {
+            throw err;
+        }
+    }
+    try {
+        process.kill(pid, signal);
+    }
+    catch (err) {
+        if (err.code !== 'ESRCH') {
+            throw err;
+        }
+    }
+}
 /**
  * Daemon manager for background server process
  */
@@ -52,15 +127,46 @@ class DaemonManager {
      * @throws Error if already running
      */
     async start(options) {
-        if (this.pidManager.isProcessRunning()) {
-            const pid = this.pidManager.readPid();
-            throw new Error(`Server is already running (PID: ${pid})`);
-        }
+        this.assertNotRunning();
         // Clean up stale PID file
         this.pidManager.removePid();
         const npmScript = options.dev ? 'dev' : 'start';
         // Use package installation directory, not current working directory
         const packageRoot = (0, paths_1.getPackageRoot)();
+        const env = this.buildChildEnv(options);
+        const { bindAddress, port, protocol } = this.resolveEndpoint(env);
+        await this.assertPortFree(bindAddress, port);
+        // Log startup with accurate settings (Stage 4 review: MF-2)
+        this.logger.info(`Starting server at ${protocol}://${bindAddress}:${port}`);
+        // Spawn detached process
+        const child = (0, child_process_1.spawn)('npm', ['run', npmScript], {
+            cwd: packageRoot,
+            env,
+            detached: true,
+            stdio: 'ignore',
+        });
+        // Unref to allow parent to exit
+        child.unref();
+        const pid = child.pid;
+        this.recordState(pid, env, bindAddress, port, protocol);
+        return pid;
+    }
+    /** Throws when the recorded server is running, or an earlier server's group lives on. */
+    assertNotRunning() {
+        if (this.pidManager.isProcessRunning()) {
+            const pid = this.pidManager.readPid();
+            throw new Error(`Server is already running (PID: ${pid})`);
+        }
+        // Issue #3087: a stale PID file is the only record of the PGID an orphaned server still runs
+        // in. Removing it here would leave `stop` with nothing to find that server by.
+        const stale = this.pidManager.readState();
+        if (stale !== null && !processAlive(stale.pid) && processGroupExists(stale.pid)) {
+            throw new Error(`Processes of an earlier server are still running (process group ${stale.pid}). ` +
+                'Run "commandmate stop" to stop them first.');
+        }
+    }
+    /** Builds the child process env from process.env, .env and the start options. */
+    buildChildEnv(options) {
         // Issue #125: Load .env file from correct location
         const envPath = (0, env_setup_1.getEnvPath)();
         const envResult = (0, dotenv_1.config)({ path: envPath });
@@ -94,6 +200,10 @@ class DaemonManager {
                 env[key] = process.env[key];
             }
         }
+        return env;
+    }
+    /** Decides bind address, port and protocol, warning when exposed without protection. */
+    resolveEndpoint(env) {
         // Issue #179: Security warning for external access - recommend reverse proxy
         const bindAddress = env.CM_BIND || '127.0.0.1';
         const port = env.CM_PORT || '3000';
@@ -105,18 +215,24 @@ class DaemonManager {
         if (bindAddress === '0.0.0.0' && !env.CM_AUTH_TOKEN_HASH && !env.CM_ALLOWED_IPS) {
             console.log(security_messages_1.REVERSE_PROXY_WARNING);
         }
-        // Log startup with accurate settings (Stage 4 review: MF-2)
-        this.logger.info(`Starting server at ${protocol}://${bindAddress}:${port}`);
-        // Spawn detached process
-        const child = (0, child_process_1.spawn)('npm', ['run', npmScript], {
-            cwd: packageRoot,
-            env,
-            detached: true,
-            stdio: 'ignore',
-        });
-        // Unref to allow parent to exit
-        child.unref();
-        const pid = child.pid;
+        return { bindAddress, port, protocol };
+    }
+    /** Throws when something else already answers on the port the server would bind. */
+    async assertPortFree(bindAddress, port) {
+        // Issue #3087: refuse to launch onto a port something else already answers on. The new
+        // server would fail to listen and exit, while every later TCP check (status, remote's
+        // readiness wait) would be answered by that other process and mistake it for this server.
+        const probeHost = bindAddress === '0.0.0.0' ? '127.0.0.1' : bindAddress;
+        if (await (0, server_ready_1.isPortInUse)(probeHost, parseInt(port, 10))) {
+            const listeners = (0, process_inspect_1.describeListeners)(parseInt(port, 10));
+            throw new Error(`Port ${port} on ${probeHost} is already in use by another process` +
+                `${listeners ? ` (${listeners})` : ''} ` +
+                'that is not the server recorded in the PID file (e.g. an earlier server left running). ' +
+                'Stop that process or choose another port.');
+        }
+    }
+    /** Persists the DaemonState; kills the spawned child and throws when the write fails. */
+    recordState(pid, env, bindAddress, port, protocol) {
         // Issue #1354/#1355/#1358: persist the daemon's version, effective settings, and a
         // process-identity signature so status/stop/start can report and verify the actual server,
         // not re-derive it from a possibly-diverged .env. The port/protocol/auth recorded here are
@@ -142,36 +258,102 @@ class DaemonManager {
             }
             throw new Error('Failed to write PID file - server may already be running');
         }
-        return pid;
     }
     /**
      * Stop daemon process
+     *
+     * Issue #3087: signals the daemon's whole process group, waits for every member to exit
+     * (escalating to SIGKILL after {@link STOP_GRACE_TIMEOUT_MS}), and then requires the recorded
+     * port to be free. "Stopped" is reported only when both hold. A recorded leader that already
+     * exited while its group lives on (the orphaned server of #3087) is stopped the same way.
+     *
      * @param force Use SIGKILL instead of SIGTERM
-     * @returns true if stopped successfully, false if not running
+     * @returns true if stopped (or the PID file was stale), false if not running or not stopped
      */
     async stop(force = false) {
-        const pid = this.pidManager.readPid();
-        if (pid === null) {
+        const state = this.pidManager.readState();
+        if (state === null) {
             return false;
         }
+        const pid = state.pid;
+        const signal = force ? 'SIGKILL' : 'SIGTERM';
         if (!this.pidManager.isProcessRunning()) {
-            // Process not running - clean up stale PID file
-            this.pidManager.removePid();
-            return true;
+            // The leader is gone. Only when its PID is entirely unused (not reused by an unrelated
+            // process) can a live group with that ID be the server it left behind.
+            const orphanedGroup = !processAlive(pid) && processGroupExists(pid);
+            if (!orphanedGroup) {
+                // Process not running - clean up stale PID file
+                this.pidManager.removePid();
+                return true;
+            }
+            this.logger.warn(`The recorded process ${pid} has exited but its server processes are still running; stopping them.`);
         }
-        const signal = force ? 'SIGKILL' : 'SIGTERM';
         try {
-            process.kill(pid, signal);
-            // Wait for process to exit
-            await this.waitForExit(pid, 10000);
-            // Clean up PID file
+            const exited = await this.terminateGroup(pid, signal);
+            if (!exited) {
+                // Issue #3087: where zombies cannot be told apart (no /proc), a group can look alive
+                // after it stopped serving. The port is what was at stake, so a released port decides.
+                if (state.port !== undefined && (await this.waitForPortRelease(state))) {
+                    this.logger.warn(`Process group ${pid} did not report exit, but port ${state.port} has been released; ` +
+                        'treating the server as stopped.');
+                    this.pidManager.removePid();
+                    return true;
+                }
+                this.logger.warn(`Process group ${pid} did not exit.`);
+                return false;
+            }
+            // Clean up PID file: nothing this file describes is alive any more.
             this.pidManager.removePid();
-            return true;
+            return await this.waitForPortRelease(state);
         }
         catch {
             return false;
         }
     }
+    /**
+     * Signal the daemon's process group and wait until no member is left.
+     *
+     * @returns true once the group is gone, false if it outlived SIGKILL
+     */
+    async terminateGroup(pid, signal) {
+        signalProcessGroup(pid, signal);
+        if (await this.waitForExit(pid, signal === 'SIGKILL' ? exports.STOP_KILL_TIMEOUT_MS : exports.STOP_GRACE_TIMEOUT_MS)) {
+            return true;
+        }
+        if (signal === 'SIGKILL') {
+            return false;
+        }
+        this.logger.warn(`Server (process group ${pid}) did not exit within ${exports.STOP_GRACE_TIMEOUT_MS / 1000}s; sending SIGKILL.`);
+        signalProcessGroup(pid, 'SIGKILL');
+        return this.waitForExit(pid, exports.STOP_KILL_TIMEOUT_MS);
+    }
+    /**
+     * Issue #3087: confirm the port the server was started on is free again.
+     *
+     * A state file from before #1354 records no port; re-deriving one from a .env that may have
+     * changed since could blame an unrelated listener, so that legacy case is not checked.
+     *
+     * @returns true when the port is free (or unknown), false if something still listens on it
+     */
+    async waitForPortRelease(state) {
+        if (state.port === undefined) {
+            return true;
+        }
+        const bind = state.bind ?? '127.0.0.1';
+        const host = bind === '0.0.0.0' ? '127.0.0.1' : bind;
+        const deadline = Date.now() + exports.PORT_RELEASE_TIMEOUT_MS;
+        for (;;) {
+            if (!(await (0, server_ready_1.isPortInUse)(host, state.port, 500))) {
+                return true;
+            }
+            if (Date.now() >= deadline) {
+                this.logger.warn(`Port ${state.port} on ${host} is still in use after the server stopped; ` +
+                    'another process is listening on it.');
+                return false;
+            }
+            await new Promise(resolve => setTimeout(resolve, 100));
+        }
+    }
     /**
      * Get daemon status
      * @returns Status object or null if no PID file
@@ -227,23 +409,23 @@ class DaemonManager {
         return this.pidManager.isProcessRunning();
     }
     /**
-     * Wait for process to exit
+     * Wait until neither the recorded PID nor any member of its process group is alive
+     * (Issue #3087: the group, because the server outlives npm).
+     *
+     * @returns true if everything exited within the timeout
      */
     async waitForExit(pid, timeout) {
         const startTime = Date.now();
         const checkInterval = 100;
-        while (Date.now() - startTime < timeout) {
-            try {
-                process.kill(pid, 0);
-                // Process still exists, wait
-                await new Promise(resolve => setTimeout(resolve, checkInterval));
+        for (;;) {
+            if (!processAlive(pid) && !processGroupExists(pid)) {
+                return true;
             }
-            catch {
-                // Process exited
-                return;
+            if (Date.now() - startTime >= timeout) {
+                return false;
             }
+            await new Promise(resolve => setTimeout(resolve, checkInterval));
         }
-        // Timeout - process may still be running
     }
 }
 exports.DaemonManager = DaemonManager;

package/dist/cli/utils/docs-reader.d.ts

@@ -13,6 +13,12 @@
  *
  * @module docs-reader
  */
+/**
+ * Whitelist of available documentation sections.
+ * [C-CONS-003] Only files listed here can be accessed via the docs command.
+ * Path traversal attempts are prevented by validating section names against this map.
+ */
+export declare const SECTION_MAP: Record<string, string>;
 /**
  * Get list of available documentation section names.
  */

package/dist/cli/utils/docs-reader.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"docs-reader.d.ts","sourceRoot":"","sources":["../../../src/cli/utils/docs-reader.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AA6DH;;GAEG;AACH,wBAAgB,oBAAoB,IAAI,MAAM,EAAE,CAE/C;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAEvD;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAYnD;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,CAAC;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC,CAsCvF"}
+{"version":3,"file":"docs-reader.d.ts","sourceRoot":"","sources":["../../../src/cli/utils/docs-reader.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAMH;;;;GAIG;AACH,eAAO,MAAM,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAU9C,CAAC;AAwCF;;GAEG;AACH,wBAAgB,oBAAoB,IAAI,MAAM,EAAE,CAE/C;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAEvD;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAYnD;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,CAAC;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC,CAsCvF"}

package/dist/cli/utils/docs-reader.js

@@ -48,6 +48,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.SECTION_MAP = void 0;
 exports.getAvailableSections = getAvailableSections;
 exports.isValidSection = isValidSection;
 exports.readSection = readSection;
@@ -60,15 +61,15 @@ const agent_operations_1 = require("../docs/agent-operations");
  * [C-CONS-003] Only files listed here can be accessed via the docs command.
  * Path traversal attempts are prevented by validating section names against this map.
  */
-const SECTION_MAP = {
-    'quick-start': 'docs/user-guide/quick-start.md',
-    'commands': 'docs/user-guide/commands-guide.md',
-    'webapp': 'docs/user-guide/webapp-guide.md',
-    'workflow-examples': 'docs/user-guide/workflow-examples.md',
-    'cli-setup': 'docs/user-guide/cli-setup-guide.md',
-    'agents': 'docs/user-guide/agents-guide.md',
-    'cmate-schedules': 'docs/user-guide/cmate-schedules-guide.md',
-    'architecture': 'docs/architecture.md',
+exports.SECTION_MAP = {
+    'quick-start': 'docs/en/user-guide/quick-start.md',
+    'commands': 'docs/en/user-guide/commands-guide.md',
+    'webapp': 'docs/en/user-guide/webapp-guide.md',
+    'workflow-examples': 'docs/en/user-guide/workflow-examples.md',
+    'cli-setup': 'docs/en/user-guide/cli-setup-guide.md',
+    'agents': 'docs/en/user-guide/agents-guide.md',
+    'cmate-schedules': 'docs/en/user-guide/cmate-schedules-guide.md',
+    'architecture': 'docs/en/architecture.md',
     'readme': 'README.md',
 };
 /**
@@ -111,13 +112,13 @@ function resolvePackageRoot() {
  * Get list of available documentation section names.
  */
 function getAvailableSections() {
-    return [...Object.keys(SECTION_MAP), ...Object.keys(EMBEDDED_SECTIONS)];
+    return [...Object.keys(exports.SECTION_MAP), ...Object.keys(EMBEDDED_SECTIONS)];
 }
 /**
  * Check if a section name is valid (exists in the whitelist or embedded).
  */
 function isValidSection(section) {
-    return section in SECTION_MAP || section in EMBEDDED_SECTIONS;
+    return section in exports.SECTION_MAP || section in EMBEDDED_SECTIONS;
 }
 /**
  * Read the content of a documentation section.
@@ -136,7 +137,7 @@ function readSection(section) {
     }
     // File-based sections
     const packageRoot = resolvePackageRoot();
-    const filePath = path.join(packageRoot, SECTION_MAP[section]);
+    const filePath = path.join(packageRoot, exports.SECTION_MAP[section]);
     return fs.readFileSync(filePath, 'utf-8');
 }
 /**
@@ -154,7 +155,7 @@ function searchDocs(query) {
     const packageRoot = resolvePackageRoot();
     const lowerQuery = query.toLowerCase();
     // Search file-based sections
-    for (const [section, relativePath] of Object.entries(SECTION_MAP)) {
+    for (const [section, relativePath] of Object.entries(exports.SECTION_MAP)) {
         const filePath = path.join(packageRoot, relativePath);
         try {
             const content = fs.readFileSync(filePath, 'utf-8');

package/dist/cli/utils/npm-runner.d.ts

@@ -47,6 +47,18 @@ export interface NpmInstallResult {
  * @returns The resolved version, or a classified failure
  */
 export declare function viewLatestVersion(packageName: string): NpmViewResult;
+/**
+ * Non-blocking twin of {@link viewLatestVersion}, for the server. [Issue #3110]
+ *
+ * The update-check route asks npm whether a release GitHub already announced
+ * has reached the registry. `spawnSync` would stall the server's event loop for
+ * the whole network round trip, so this uses `execFile` (array args, no shell —
+ * MF-SEC-1 holds) under the same timeout and failure classification.
+ *
+ * @param packageName - Package name (e.g. `commandmate`)
+ * @returns The resolved version, or a classified failure. Never rejects.
+ */
+export declare function viewLatestVersionAsync(packageName: string): Promise<NpmViewResult>;
 /**
  * Install the latest published version of a package globally.
  *

package/dist/cli/utils/npm-runner.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"npm-runner.d.ts","sourceRoot":"","sources":["../../../src/cli/utils/npm-runner.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAMH,wFAAwF;AACxF,eAAO,MAAM,mBAAmB,QAAS,CAAC;AAE1C,mFAAmF;AACnF,eAAO,MAAM,mBAAmB,OAAQ,CAAC;AAEzC;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,kCAAkC;IAClC,OAAO,EAAE,OAAO,CAAC;IACjB,2CAA2C;IAC3C,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,yDAAyD;IACzD,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,oCAAoC;IACpC,OAAO,EAAE,OAAO,CAAC;IACjB,0DAA0D;IAC1D,gBAAgB,EAAE,OAAO,CAAC;IAC1B,yDAAyD;IACzD,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,MAAM,GAAG,aAAa,CA+BpE;AAED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAAC,WAAW,EAAE,MAAM,GAAG,gBAAgB,CAwCzE;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,uDAAuD;IACvD,IAAI,EAAE,MAAM,CAAC;IACb,6EAA6E;IAC7E,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,sBAAsB,CAAC,WAAW,EAAE,MAAM,GAAG,kBAAkB,GAAG,IAAI,CAsBrF"}
+{"version":3,"file":"npm-runner.d.ts","sourceRoot":"","sources":["../../../src/cli/utils/npm-runner.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAMH,wFAAwF;AACxF,eAAO,MAAM,mBAAmB,QAAS,CAAC;AAE1C,mFAAmF;AACnF,eAAO,MAAM,mBAAmB,OAAQ,CAAC;AAEzC;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,kCAAkC;IAClC,OAAO,EAAE,OAAO,CAAC;IACjB,2CAA2C;IAC3C,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,yDAAyD;IACzD,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,oCAAoC;IACpC,OAAO,EAAE,OAAO,CAAC;IACjB,0DAA0D;IAC1D,gBAAgB,EAAE,OAAO,CAAC;IAC1B,yDAAyD;IACzD,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,MAAM,GAAG,aAAa,CA+BpE;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,sBAAsB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CA6BlF;AAED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAAC,WAAW,EAAE,MAAM,GAAG,gBAAgB,CAwCzE;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,uDAAuD;IACvD,IAAI,EAAE,MAAM,CAAC;IACb,6EAA6E;IAC7E,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,sBAAsB,CAAC,WAAW,EAAE,MAAM,GAAG,kBAAkB,GAAG,IAAI,CAsBrF"}

package/dist/cli/utils/npm-runner.js

@@ -18,6 +18,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.NPM_ROOT_TIMEOUT_MS = exports.NPM_VIEW_TIMEOUT_MS = void 0;
 exports.viewLatestVersion = viewLatestVersion;
+exports.viewLatestVersionAsync = viewLatestVersionAsync;
 exports.installGlobalLatest = installGlobalLatest;
 exports.findGlobalInstallation = findGlobalInstallation;
 const child_process_1 = require("child_process");
@@ -61,6 +62,41 @@ function viewLatestVersion(packageName) {
     }
     return { success: true, version };
 }
+/**
+ * Non-blocking twin of {@link viewLatestVersion}, for the server. [Issue #3110]
+ *
+ * The update-check route asks npm whether a release GitHub already announced
+ * has reached the registry. `spawnSync` would stall the server's event loop for
+ * the whole network round trip, so this uses `execFile` (array args, no shell —
+ * MF-SEC-1 holds) under the same timeout and failure classification.
+ *
+ * @param packageName - Package name (e.g. `commandmate`)
+ * @returns The resolved version, or a classified failure. Never rejects.
+ */
+function viewLatestVersionAsync(packageName) {
+    return new Promise((resolve) => {
+        (0, child_process_1.execFile)('npm', ['view', packageName, 'version'], { encoding: 'utf-8', timeout: exports.NPM_VIEW_TIMEOUT_MS }, (error, stdout, stderr) => {
+            if (error) {
+                const errnoError = error;
+                if (errnoError.code === 'ENOENT') {
+                    resolve({
+                        success: false,
+                        error: 'npm command not found. Install Node.js/npm and try again.',
+                    });
+                    return;
+                }
+                resolve({ success: false, error: readStream(stderr) || errnoError.message });
+                return;
+            }
+            const version = readStream(stdout);
+            if (!version) {
+                resolve({ success: false, error: 'npm view returned no version' });
+                return;
+            }
+            resolve({ success: true, version });
+        });
+    });
+}
 /**
  * Install the latest published version of a package globally.
  *

package/dist/cli/utils/process-inspect.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Best-effort process inspection for stop/start (Issue #3087)
+ *
+ * - Zombies: `kill(pid, 0)` succeeds for a zombie, so without an init process
+ *   (a container whose PID 1 never reaps) a stopped server's group looked alive
+ *   forever. On Linux, /proc tells a zombie apart; elsewhere nothing is known
+ *   and callers keep their signal-based answer.
+ * - Listeners: when something answers on the configured port but is not the
+ *   server the PID file describes, the user is told which PID holds it.
+ *
+ * Every function here is read-only and never throws.
+ *
+ * @module process-inspect
+ */
+interface ProcStat {
+    state: string;
+    pgrp: number;
+}
+/**
+ * Parse `/proc/<pid>/stat`. The command name is parenthesised and may itself
+ * contain spaces or parentheses, so fields are read after the LAST `)`.
+ */
+export declare function parseProcStat(content: string): ProcStat | null;
+/**
+ * @returns true when /proc reports the process as a zombie (or dead); false when it is
+ *   running, absent, or the platform has no /proc
+ */
+export declare function isZombieProcess(pid: number): boolean;
+/**
+ * States of every process whose process group is `pgid`.
+ *
+ * @returns the state letters (possibly empty), or null when /proc cannot be read
+ *   (non-Linux), in which case nothing is known
+ */
+export declare function listProcessGroupStates(pgid: number): string[] | null;
+/** @returns true when a /proc state letter means the process no longer runs */
+export declare function isExitedState(state: string): boolean;
+/**
+ * PIDs listening on a TCP port: /proc on Linux, `lsof` elsewhere.
+ *
+ * @returns the PIDs found; empty when none are visible (another user's process, or no tool)
+ */
+export declare function findListeningPids(port: number): number[];
+/**
+ * One-line description of a process for an error message.
+ *
+ * @returns the command line, or null when it cannot be read
+ */
+export declare function describeProcess(pid: number): string | null;
+/**
+ * "PID 875 (node dist/server/server.js), PID 876" — or null when no PID is visible.
+ */
+export declare function describeListeners(port: number): string | null;
+export {};
+//# sourceMappingURL=process-inspect.d.ts.map

package/dist/cli/utils/process-inspect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"process-inspect.d.ts","sourceRoot":"","sources":["../../../src/cli/utils/process-inspect.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAQH,UAAU,QAAQ;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,QAAQ,GAAG,IAAI,CAQ9D;AAUD;;;GAGG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAIpD;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,IAAI,CAmBpE;AAED,+EAA+E;AAC/E,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAEpD;AA0ED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAExD;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAe1D;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAS7D"}