@noego/app 0.0.11 → 0.0.13

package/AGENTS.md

@@ -12,37 +12,43 @@ Objective
 
   Entry Points
 
-  - Server entry: `noblelaw/index.ts` (spawns/hosts Express + @noego/dinner API + @noego/forge SSR UI)
-  - Page entry: `noblelaw/ui/index.html` (loads `noblelaw/ui/client.ts` to hydrate in browser)
+  - Server entry: `{project}/index.ts` (spawns/hosts Express + @noego/dinner API + @noego/forge SSR UI)
+  - Page entry: `{project}/ui/index.html` (loads `{project}/ui/client.ts` to hydrate in browser)
 
 Repository Roots and Path Referencing
 
-- Unless explicitly prefixed, relative paths in this document refer to the application project root (`--root`), which in our environment is `noblelaw` at `/Users/shavauhngabay/dev/noblelaw`.
+- Unless explicitly prefixed, relative paths in this document refer to the application project root (`--root`).
+- Available website projects:
+  - bashly: `/Users/shavauhngabay/dev/noego_manager/websites/bashly`
+  - mindful_essence: `/Users/shavauhngabay/dev/noego_manager/websites/mindful_essence`
+  - noego_landing: `/Users/shavauhngabay/dev/noego_manager/websites/noego_landing`
+  - {project}: `/Users/shavauhngabay/dev/noego_manager/websites/{project}`
 - Source checkouts for frameworks/tools:
-  - Forge: `/Users/shavauhngabay/dev/ego/forge`
-  - Dinner: `/Users/shavauhngabay/dev/noego/dinner`
-  - Sqlstack: `/Users/shavauhngabay/dev/ego/sqlstack`
-  - App (this CLI): `/Users/shavauhngabay/dev/app`
-- Example dist outputs in this doc are under the application project: `noblelaw/dist/...`.
+  - Forge: `/Users/shavauhngabay/dev/noego_manager/noego/forge`
+  - Dinner: `/Users/shavauhngabay/dev/noego_manager/noego/dinner`
+  - Sqlstack: `/Users/shavauhngabay/dev/noego_manager/noego/sqlstack`
+  - App (this CLI): `/Users/shavauhngabay/dev/noego_manager/noego/app`
+- Example dist outputs in this doc are under the application project: `{project}/dist/...`.
+- In examples below, `{project}` refers to any of the website projects listed above.
 
   Current Architecture
 
   - API
-      - @noego/dinner (source: `/Users/shavauhngabay/dev/noego/dinner`) loads OpenAPI (default noblelaw uses `noblelaw/server/stitch.yaml`), dynamically wires controllers (`noblelaw/server/controller/**`) and middleware (`noblelaw/middleware/**`) based on configured base dirs
+      - @noego/dinner (source: `/Users/shavauhngabay/dev/noego_manager/noego/dinner`) loads OpenAPI (uses `{project}/server/stitch.yaml`), dynamically wires controllers (`{project}/server/controller/**`) and middleware (`{project}/middleware/**`) based on configured base dirs
       - Paths are resolved with process.cwd() and are runtime file-based; both controllers base and middleware base are configurable
   - UI SSR
-      - @noego/forge/server (source: `/Users/shavauhngabay/dev/ego/forge`) uses options from `noblelaw/ui/options.ts`
+      - @noego/forge/server (source: `/Users/shavauhngabay/dev/noego_manager/noego/forge`) uses options from `{project}/ui/options.ts`
       - In dev, Vite middleware compiles .svelte on demand
       - In prod, must be precompiled (no loaders)
   - Client
-      - Hydration bootstrap at `noblelaw/ui/client.ts`, page template `noblelaw/ui/index.html`
+      - Hydration bootstrap at `{project}/ui/client.ts`, page template `{project}/ui/index.html`
   - DB
-      - Repositories (server/repo/**) use sqlstack decorators (source: `/Users/shavauhngabay/dev/ego/sqlstack`)
+      - Repositories (server/repo/**) use sqlstack decorators (source: `/Users/shavauhngabay/dev/noego_manager/noego/sqlstack`)
       - sqlstack reads .sql from filesystem at runtime, adjacent to transpiled repo JS
   - Tests/CI
       - Jest + Python runner; not directly relevant to build targets, but artifacts must be runnable in CI
   - Config files
-      - `noblelaw/tsconfig.json`, `noblelaw/vite.config.js`, `noblelaw/proper.json`, `noblelaw/server/stitch.yaml`, `noblelaw/ui/stitch.yaml`
+      - `{project}/tsconfig.json`, `{project}/vite.config.js`, `{project}/proper.json`, `{project}/server/stitch.yaml`, `{project}/ui/stitch.yaml`
 
   Constraints and Implications
 
@@ -60,7 +66,7 @@ Repository Roots and Path Referencing
   CLI Contract
 
   - Command: app build --server index.ts --page ui/index.html
-  - Options (all optional; default values assume noblelaw layout)
+  - Options (all optional; default values assume {project} layout)
       - --root . project root
       - --out dist output directory root
       - --server-root . where to resolve server entry from (default --root)
@@ -138,24 +144,24 @@ YAML Configuration (Preferred)
   - While every option is available via CLI, the preferred way to configure App is a YAML config file committed to the repo. This provides a single, reviewable source of truth. CLI flags remain available for ad‑hoc overrides.
 
 - Location and discovery
-  - Default filenames searched at the application root (`noblelaw`): `app.yaml`, `app.yml`, `app.config.yaml`, `app.config.yml`, or `app.config.json`.
+  - Default filenames searched at the application root (`{project}`): `app.yaml`, `app.yml`, `app.config.yaml`, `app.config.yml`, or `app.config.json`.
   - A future `--config <path>` CLI flag may explicitly point to a YAML file. Paths inside the YAML resolve relative to the YAML file itself unless absolute.
 
 - Schema (high‑level)
   - Server
-    - `entry`: e.g., `noblelaw/index.ts`
-    - `rootDir`: e.g., `noblelaw`
-    - `controllers`: e.g., `noblelaw/server/controller`
-    - `middleware`: e.g., `noblelaw/middleware`
-    - `openapi`: e.g., `noblelaw/server/stitch.yaml`
-    - `sqlGlobs`: list of globs, e.g., `['noblelaw/server/repo/**/*.sql']`
+    - `entry`: e.g., `{project}/index.ts`
+    - `rootDir`: e.g., `{project}`
+    - `controllers`: e.g., `{project}/server/controller`
+    - `middleware`: e.g., `{project}/middleware`
+    - `openapi`: e.g., `{project}/server/stitch.yaml`
+    - `sqlGlobs`: list of globs, e.g., `['{project}/server/repo/**/*.sql']`
   - UI
-    - `page`: e.g., `noblelaw/ui/index.html`
-    - `options`: e.g., `noblelaw/ui/options.ts` (Forge server options entry)
-    - `rootDir`: e.g., `noblelaw/ui`
-    - `openapi`: e.g., `noblelaw/ui/stitch.yaml`
-    - `assets`: list of globs, e.g., `['noblelaw/ui/resources/**']`
-    - `clientExclude`: list of globs for CSR exclusions, e.g., `['noblelaw/server/**', 'noblelaw/middleware/**']`
+    - `page`: e.g., `{project}/ui/index.html`
+    - `options`: e.g., `{project}/ui/options.ts` (Forge server options entry)
+    - `rootDir`: e.g., `{project}/ui`
+    - `openapi`: e.g., `{project}/ui/stitch.yaml`
+    - `assets`: list of globs, e.g., `['{project}/ui/resources/**']`
+    - `clientExclude`: list of globs for CSR exclusions, e.g., `['{project}/server/**', '{project}/middleware/**']`
   - Dev
     - `watch`: boolean
     - `watchPaths`: list of globs (preferred)
@@ -169,51 +175,51 @@ YAML Configuration (Preferred)
       - `configFile`: path to a Vite config for SSR build
       - `override`: object or path to a JSON file with deep‑merge overrides
   - Output
-    - `outDir`: e.g., `noblelaw/dist`
+    - `outDir`: e.g., `{project}/dist`
 
 - Referencing JSON files
   - Any `override` field under `vite.client` or `vite.ssr` may be either an inline object or a string path to a JSON file. App will load JSON and deep‑merge it into the Vite config (after the file’s own `configFile` is applied, before enforcing invariants like `outDir`).
   - This pattern can be extended to other future sections where JSON is a convenient format.
 
-- Example: `noblelaw/app.yaml`
+- Example: `{project}/app.yaml`
   - server:
-      entry: noblelaw/index.ts
-      rootDir: noblelaw
-      controllers: noblelaw/server/controller
-      middleware: noblelaw/middleware
-      openapi: noblelaw/server/stitch.yaml
+      entry: {project}/index.ts
+      rootDir: {project}
+      controllers: {project}/server/controller
+      middleware: {project}/middleware
+      openapi: {project}/server/stitch.yaml
       sqlGlobs:
-        - noblelaw/server/repo/**/*.sql
+        - {project}/server/repo/**/*.sql
   - ui:
-      page: noblelaw/ui/index.html
-      options: noblelaw/ui/options.ts
-      rootDir: noblelaw/ui
-      openapi: noblelaw/ui/stitch.yaml
+      page: {project}/ui/index.html
+      options: {project}/ui/options.ts
+      rootDir: {project}/ui
+      openapi: {project}/ui/stitch.yaml
       assets:
-        - noblelaw/ui/resources/**
-        - noblelaw/ui/styles/**
+        - {project}/ui/resources/**
+        - {project}/ui/styles/**
       clientExclude:
-        - noblelaw/server/**
-        - noblelaw/middleware/**
+        - {project}/server/**
+        - {project}/middleware/**
   - dev:
       watch: true
       watchPaths:
-        - noblelaw/server/**/*.ts
-        - noblelaw/ui/openapi/**/*.yaml
+        - {project}/server/**/*.ts
+        - {project}/ui/openapi/**/*.yaml
       splitServe: true
       frontendCmd: vite
   - vite:
       client:
-        configFile: noblelaw/vite.config.js
-        override: noblelaw/vite.client.override.json
+        configFile: {project}/vite.config.js
+        override: {project}/vite.client.override.json
       ssr:
-        configFile: noblelaw/vite.config.js
+        configFile: {project}/vite.config.js
         override:
           build:
             ssr: true
             rollupOptions:
               preserveModules: true
-  - outDir: noblelaw/dist
+  - outDir: {project}/dist
 
 - Precedence and merging
   - Defaults → YAML → CLI: App starts from sane defaults, applies YAML config, then applies CLI flags as the final layer. Required invariants for production builds still apply (e.g., outDir, manifest, SSR flags), unless explicitly documented otherwise.
@@ -224,21 +230,21 @@ OpenAPI‑Driven Discovery (Build/Serve Optimization)
   - The OpenAPI specs (server and UI stitch YAML) already declare every API route, controller reference, middleware reference, and UI view/layout. App can parse these ahead of time to optimize build and reduce required options.
 
 - What App derives
-  - Server OpenAPI (`noblelaw/server/stitch.yaml`):
+  - Server OpenAPI (`{project}/server/stitch.yaml`):
     - All controller identifiers from `x-controller` across routes.
     - All middleware identifiers from `x-middleware`.
-  - UI OpenAPI (`noblelaw/ui/stitch.yaml`):
+  - UI OpenAPI (`{project}/ui/stitch.yaml`):
     - All pages, layouts, and component paths that need SSR precompilation.
 
 - How we use it
   - SSR entry set: feed the exact list of Svelte components (views/layouts) into the SSR Vite build, avoiding filesystem globs.
-  - Validation: after transpile/copy, verify all referenced controllers/middleware resolve under `noblelaw/dist` and fail fast with actionable errors.
+  - Validation: after transpile/copy, verify all referenced controllers/middleware resolve under `{project}/dist` and fail fast with actionable errors.
   - Manifest: emit a debug manifest including discovered controllers, middleware, and SSR components for troubleshooting.
 
 - Option minimization (sane defaults with override)
-  - If `--controllers` or `--middleware` are omitted, App attempts to infer base directories by computing the longest common directory prefix from discovered identifiers. Example: if `x-controller` uses `controllers/*.controller`, infer `noblelaw/server/controller`.
-  - If inference fails or is ambiguous, App falls back to NobleLaw defaults and warns. Users retain full control by setting flags explicitly.
-  - `--ui-openapi` remains required for SSR discovery unless the project embeds its location in code; App defaults to `noblelaw/ui/stitch.yaml`.
+  - If `--controllers` or `--middleware` are omitted, App attempts to infer base directories by computing the longest common directory prefix from discovered identifiers. Example: if `x-controller` uses `controllers/*.controller`, infer `{project}/server/controller`.
+  - If inference fails or is ambiguous, App falls back to {project} defaults and warns. Users retain full control by setting flags explicitly.
+  - `--ui-openapi` remains required for SSR discovery unless the project embeds its location in code; App defaults to `{project}/ui/stitch.yaml`.
 
 - Serve improvements
   - During `app serve`, App may parse OpenAPI once at startup to log missing controllers/middleware early, while still delegating runtime wiring to Dinner/Forge.
@@ -250,16 +256,16 @@ OpenAPI‑Driven Discovery (Build/Serve Optimization)
       - Treat CLI values as relative to --root unless absolute
       - --page determines --ui-root when not provided (dirname of --page)
   - Output layout (example)
-      - `noblelaw/dist/server/**` transpiled JS, mirrored structure of `noblelaw/server/**` and `noblelaw/middleware/**`, plus copied `.sql` and `noblelaw/server/openapi/**`, `noblelaw/server/stitch.yaml`
-      - `noblelaw/dist/client/**` bundled CSR assets + `manifest.json`
-      - `noblelaw/dist/ssr/**` SSR bundle/modules + `ssr-manifest.json` (or embed SSR output under `noblelaw/dist/server/ssr/**`)
+      - `{project}/dist/server/**` transpiled JS, mirrored structure of `{project}/server/**` and `{project}/middleware/**`, plus copied `.sql` and `{project}/server/openapi/**`, `{project}/server/stitch.yaml`
+      - `{project}/dist/client/**` bundled CSR assets + `manifest.json`
+      - `{project}/dist/ssr/**` SSR bundle/modules + `ssr-manifest.json` (or embed SSR output under `{project}/dist/server/ssr/**`)
   - Runtime path resolution
       - All server code that used process.cwd() should continue to work if server is launched with cwd at dist root OR the dist structure mirrors
         source-tree paths
       - App must ensure:
-          - Dinner’s `openapi_path` points to a real YAML under `noblelaw/dist/server/...`
-          - Forge’s `open_api_path` resolves correctly under `noblelaw/dist` (either copy UI YAML or generate a stitched snapshot consumed by SSR)
-          - sqlstack finds `.sql` files next to the transpiled repo JS under `noblelaw/dist/server/repo/**`
+          - Dinner’s `openapi_path` points to a real YAML under `{project}/dist/server/...`
+          - Forge’s `open_api_path` resolves correctly under `{project}/dist` (either copy UI YAML or generate a stitched snapshot consumed by SSR)
+          - sqlstack finds `.sql` files next to the transpiled repo JS under `{project}/dist/server/repo/**`
       - If any path cannot be made to resolve from cwd reliably, App provides a tiny generated bootstrap wrapper that rewrites those path
         strings to __dirname-based equivalents at build time (no change to public interfaces)
 
@@ -285,8 +291,8 @@ Path Customization and Framework Mapping
   - Root directory for SQL resolution is inferred from decorator location or explicitly passed via @Query(). No bundling or inlining — files must exist at runtime.
 
 - App CLI flags → runtime mapping
-  - --controllers: the source directory to mirror into dist for runtime controller discovery. Must correspond to the app’s controllers_base_path at runtime. Defaults to server/controller for NobleLaw, but any path is valid.
-  - --middleware: the source directory to mirror into dist for runtime middleware discovery. Must correspond to the app’s middleware_path (or controllers_base_path fallback). Defaults to middleware for NobleLaw.
+  - --controllers: the source directory to mirror into dist for runtime controller discovery. Must correspond to the app’s controllers_base_path at runtime. Defaults to server/controller for {project}, but any path is valid.
+  - --middleware: the source directory to mirror into dist for runtime middleware discovery. Must correspond to the app’s middleware_path (or controllers_base_path fallback). Defaults to middleware for {project}.
   - --openapi / --ui-openapi: OpenAPI stitch YAML locations for API and UI. App copies these into dist/server and dist/ui respectively.
   - --sql-glob: one or more glob patterns for SQL files to copy next to compiled JS outputs. Use this to support custom repo locations.
   - --page / --ui-root: determines client entry and build root used by Vite; paths are normalized relative to --root unless absolute.
@@ -332,7 +338,7 @@ Client Bundle Exclusions
   - Prevent accidental inclusion of server-only code in the browser bundle while allowing projects to keep shared TypeScript without extensions.
 
 - CLI
-  - `--client-exclude <glob>`: may be specified multiple times. Paths are resolved relative to `--root` unless absolute. Example defaults for NobleLaw: `server/**`, `middleware/**`.
+  - `--client-exclude <glob>`: may be specified multiple times. Paths are resolved relative to `--root` unless absolute. Example defaults for {project}: `server/**`, `middleware/**`.
 
 - Behavior
   - During the Vite/Rollup client build, App installs a plugin that intercepts resolved module IDs. If the absolute file path matches any exclusion pattern, the loader returns a virtual stub module instead of the real source.
@@ -371,7 +377,7 @@ Non‑Default Layout Examples
           - `--watch` enables restart on server‑side changes
           - `--watch-path <glob>` adds additional watch patterns (repeatable). Preferred: use globs to cover directories rather than listing many files.
           - Defaults watch: controllers, middleware, server OpenAPI (and openapi/**), UI OpenAPI (and openapi/**), and SQL globs
-          - UI Svelte/TS/CSS/HTML under `noblelaw/ui/**` are excluded from restart and continue to reload via Vite HMR
+          - UI Svelte/TS/CSS/HTML under `{project}/ui/**` are excluded from restart and continue to reload via Vite HMR
         - Optional split processes in watch mode:
           - `--split-serve` starts the frontend dev server (vite) as a separate process so API restarts don’t disrupt HMR
           - `--frontend-cmd vite` selects the frontend runner (currently only vite supported)
@@ -412,9 +418,9 @@ Non‑Default Layout Examples
   Acceptance Criteria
 
   - Running app build --server index.ts --page ui/index.html produces:
-      - `noblelaw/dist/server` transpiled ESM with mirrored structure and copied `.sql`, OpenAPI YAML
-      - `noblelaw/dist/client` minified assets + client manifest
-      - `noblelaw/dist/ssr` precompiled SSR output + SSR manifest (or nested under `noblelaw/dist/server/ssr`)
+      - `{project}/dist/server` transpiled ESM with mirrored structure and copied `.sql`, OpenAPI YAML
+      - `{project}/dist/client` minified assets + client manifest
+      - `{project}/dist/ssr` precompiled SSR output + SSR manifest (or nested under `{project}/dist/server/ssr`)
   - Starting node dist/server/index.js:
       - API endpoints function unchanged
       - GET / returns SSR HTML; hydration works
@@ -433,7 +439,7 @@ Non‑Default Layout Examples
       - Record both source and output absolute paths inside a build manifest for troubleshooting
       - If the app is started from outside dist, require cwd to be dist (documented), or generate a wrapper that sets process.chdir(__dirname +
         '/../') at startup
-  - Defaults for noblelaw
+  - Defaults for {project}
       - --root .
       - --server index.ts
       - --page ui/index.html
@@ -448,10 +454,13 @@ Non‑Default Layout Examples
 
 
 Framework Reference
-`/Users/shavauhngabay/dev/ego/forge`
-`/Users/shavauhngabay/dev/noego/dinner`
-`/Users/shavauhngabay/dev/ego/sqlstack`
+`/Users/shavauhngabay/dev/noego_manager/noego/forge`
+`/Users/shavauhngabay/dev/noego_manager/noego/dinner`
+`/Users/shavauhngabay/dev/noego_manager/noego/sqlstack`
 
 
-Project Reference
-`/Users/shavauhngabay/dev/noblelaw`
+Project References
+`/Users/shavauhngabay/dev/noego_manager/websites/bashly`
+`/Users/shavauhngabay/dev/noego_manager/websites/mindful_essence`
+`/Users/shavauhngabay/dev/noego_manager/websites/noego_landing`
+`/Users/shavauhngabay/dev/noego_manager/websites/noblelaw`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@noego/app",
-  "version": "0.0.11",
+  "version": "0.0.13",
   "description": "Production build tool for Dinner/Forge apps.",
   "type": "module",
   "bin": {
@@ -33,6 +33,7 @@
     "glob-parent": "^6.0.2",
     "http-proxy": "^1.18.1",
     "picomatch": "^2.3.1",
+    "rxjs": "^7.8.1",
     "yaml": "^2.6.0"
   },
   "peerDependencies": {

package/src/commands/dev.js

@@ -5,6 +5,11 @@ import { createBuildContext } from '../build/context.js';
 import { findConfigFile } from '../runtime/index.js';
 import { loadConfig } from '../runtime/config-loader.js';
 import globParent from 'glob-parent';
+import { Subject, concat, of, EMPTY } from 'rxjs';
+import { debounceTime, filter, exhaustMap, tap, catchError, takeUntil, finalize, map, switchMap } from 'rxjs/operators';
+import { waitForPortFree } from '../utils/port.js';
+import { stopProcess, killProcessTree as killProcessTreeUtil } from '../utils/process-observable.js';
+import { watcherToObservable, FileEventType } from '../utils/file-watcher-observable.js';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 
@@ -444,61 +449,191 @@ async function runSplitServeWithWatch(context, tsxExecutable, tsxArgs, baseEnv,
 
   let backendProc = null;
   let frontendProc = null;
-  let pending = false;
   let backendRestartCount = 0;
   let frontendRestartCount = 0;
   let isShuttingDown = false;
 
+  // RxJS subjects for managing restart streams
+  const shutdownSubject = new Subject();
+  const backendRestartSubject = new Subject();
+  const frontendRestartSubject = new Subject();
+  const subscriptions = [];
+
+  // Crash restart tracking
+  const MAX_CRASH_RESTARTS = 3;
+  const CRASH_RESTART_DELAY = 2000; // 2 seconds between crash restarts
+  const STABILITY_THRESHOLD = 30000; // Reset crash counter if running 30+ seconds
+  let backendCrashRestarts = 0;
+  let frontendCrashRestarts = 0;
+  let backendStartTime = 0;
+  let frontendStartTime = 0;
+
   const startBackend = () => {
     backendRestartCount++;
+    backendStartTime = Date.now();
     logger.info(`🚀 [RESTART #${backendRestartCount}] Starting backend on port ${backendPort}...`);
     const backendEnv = {
       ...baseEnv,
       NOEGO_SERVICE: 'backend',
       NOEGO_PORT: String(backendPort)
     };
-    
+
     backendProc = spawn(tsxExecutable, tsxArgs, {
       cwd: context.config.rootDir,
       env: backendEnv,
       stdio: 'inherit',
       detached: false
     });
-    
-    backendProc.on('exit', (code) => {
+
+    backendProc.on('exit', (code, signal) => {
+      if (isShuttingDown) return;
+
+      // Check if process was stable (ran for a while) - reset crash counter
+      const runDuration = Date.now() - backendStartTime;
+      if (runDuration > STABILITY_THRESHOLD) {
+        backendCrashRestarts = 0;
+      }
+
       if (code !== null && code !== 0) {
-        logger.error(`Backend exited with code ${code}`);
+        logger.error(`[BACKEND] Exited with code ${code}, signal ${signal}`);
+
+        // Auto-restart on crash if under limit
+        if (backendCrashRestarts < MAX_CRASH_RESTARTS) {
+          backendCrashRestarts++;
+          logger.warn(`[BACKEND] Crash detected. Auto-restart ${backendCrashRestarts}/${MAX_CRASH_RESTARTS} in ${CRASH_RESTART_DELAY}ms...`);
+          setTimeout(() => {
+            if (!isShuttingDown) {
+              startBackend();
+            }
+          }, CRASH_RESTART_DELAY);
+        } else {
+          logger.error(`[BACKEND] Exceeded max crash restarts (${MAX_CRASH_RESTARTS}). Shutting down...`);
+          shutdown('backend-exceeded-restarts', 1, 'backend-crash');
+        }
       }
     });
+
+    backendProc.on('error', (err) => {
+      logger.error(`[BACKEND] Spawn error: ${err.message}`);
+    });
   };
-  
+
   const startFrontend = () => {
     frontendRestartCount++;
+    frontendStartTime = Date.now();
     logger.info(`🚀 [RESTART #${frontendRestartCount}] Starting frontend on port ${frontendPort}...`);
     const frontendEnv = {
       ...baseEnv,
       NOEGO_SERVICE: 'frontend',
       NOEGO_PORT: String(frontendPort)
     };
-    
+
     frontendProc = spawn(tsxExecutable, tsxArgs, {
       cwd: context.config.rootDir,
       env: frontendEnv,
       stdio: 'inherit',
       detached: false
     });
-    
-    frontendProc.on('exit', (code) => {
+
+    frontendProc.on('exit', (code, signal) => {
+      if (isShuttingDown) return;
+
+      // Check if process was stable (ran for a while) - reset crash counter
+      const runDuration = Date.now() - frontendStartTime;
+      if (runDuration > STABILITY_THRESHOLD) {
+        frontendCrashRestarts = 0;
+      }
+
       if (code !== null && code !== 0) {
-        logger.error(`Frontend exited with code ${code}`);
+        logger.error(`[FRONTEND] Exited with code ${code}, signal ${signal}`);
+
+        // Auto-restart on crash if under limit
+        if (frontendCrashRestarts < MAX_CRASH_RESTARTS) {
+          frontendCrashRestarts++;
+          logger.warn(`[FRONTEND] Crash detected. Auto-restart ${frontendCrashRestarts}/${MAX_CRASH_RESTARTS} in ${CRASH_RESTART_DELAY}ms...`);
+          setTimeout(() => {
+            if (!isShuttingDown) {
+              startFrontend();
+            }
+          }, CRASH_RESTART_DELAY);
+        } else {
+          logger.error(`[FRONTEND] Exceeded max crash restarts (${MAX_CRASH_RESTARTS}). Shutting down...`);
+          shutdown('frontend-exceeded-restarts', 1, 'frontend-crash');
+        }
       }
     });
+
+    frontendProc.on('error', (err) => {
+      logger.error(`[FRONTEND] Spawn error: ${err.message}`);
+    });
   };
-  
+
+  // RxJS-based stop functions that VERIFY port release before resolving
+  // This is the KEY FIX for the race condition bug
+
+  /**
+   * Stop backend and wait for port to be verified free
+   * Returns an Observable that completes only when the port is confirmed available
+   */
+  const stopBackendAndWait$ = () => {
+    if (!backendProc) {
+      return of(undefined);
+    }
+
+    logger.info(`⏹️  Stopping backend (preparing for restart #${backendRestartCount + 1})...`);
+    const proc = backendProc;
+
+    return concat(
+      // First: Stop the process and wait for exit
+      stopProcess(proc, 2000, killProcessTree),
+      // Then: VERIFY port is actually free (THIS IS THE KEY FIX)
+      waitForPortFree(backendPort, 5000, 50).pipe(
+        tap(() => logger.debug(`[BACKEND] Port ${backendPort} verified free`))
+      )
+    ).pipe(
+      tap(() => { backendProc = null; }),
+      catchError((err) => {
+        logger.warn(`[BACKEND] Stop warning: ${err.message}. Proceeding anyway.`);
+        backendProc = null;
+        return of(undefined);
+      })
+    );
+  };
+
+  /**
+   * Stop frontend and wait for port to be verified free
+   * Returns an Observable that completes only when the port is confirmed available
+   */
+  const stopFrontendAndWait$ = () => {
+    if (!frontendProc) {
+      return of(undefined);
+    }
+
+    logger.info(`⏹️  Stopping frontend (preparing for restart #${frontendRestartCount + 1})...`);
+    const proc = frontendProc;
+
+    return concat(
+      // First: Stop the process and wait for exit
+      stopProcess(proc, 2000, killProcessTree),
+      // Then: VERIFY port is actually free (THIS IS THE KEY FIX)
+      waitForPortFree(frontendPort, 5000, 50).pipe(
+        tap(() => logger.debug(`[FRONTEND] Port ${frontendPort} verified free`))
+      )
+    ).pipe(
+      tap(() => { frontendProc = null; }),
+      catchError((err) => {
+        logger.warn(`[FRONTEND] Stop warning: ${err.message}. Proceeding anyway.`);
+        frontendProc = null;
+        return of(undefined);
+      })
+    );
+  };
+
+  // Legacy Promise-based stop functions for shutdown (non-RxJS paths)
   const stopBackend = () =>
     new Promise((resolve) => {
       if (!backendProc) return resolve();
-      logger.info(`⏹️  Stopping backend (preparing for restart #${backendRestartCount + 1})...`);
+      logger.info(`⏹️  Stopping backend...`);
       const pid = backendProc.pid;
       let exited = false;
 
@@ -521,11 +656,11 @@ async function runSplitServeWithWatch(context, tsxExecutable, tsxArgs, baseEnv,
         resolve();
       }
     });
-  
+
   const stopFrontend = () =>
     new Promise((resolve) => {
       if (!frontendProc) return resolve();
-      logger.info(`⏹️  Stopping frontend (preparing for restart #${frontendRestartCount + 1})...`);
+      logger.info(`⏹️  Stopping frontend...`);
       const pid = frontendProc.pid;
       let exited = false;
 
@@ -549,13 +684,27 @@ async function runSplitServeWithWatch(context, tsxExecutable, tsxArgs, baseEnv,
       }
     });
 
-  async function shutdown(signal = 'SIGTERM', exitCode = 0) {
+  async function shutdown(signal = 'SIGTERM', exitCode = 0, source = 'unknown') {
     if (isShuttingDown) return;
     isShuttingDown = true;
 
+    logger.info(`[SHUTDOWN] source=${source}, signal=${signal}, exitCode=${exitCode}`);
     logger.info(`Shutting down split-serve processes (signal: ${signal})...`);
 
     try {
+      // Signal RxJS streams to stop
+      shutdownSubject.next();
+      shutdownSubject.complete();
+
+      // Unsubscribe from all RxJS subscriptions
+      for (const sub of subscriptions) {
+        try {
+          sub.unsubscribe();
+        } catch {
+          // Ignore unsubscribe errors
+        }
+      }
+
       if (watcher) {
         await watcher.close();
       }
@@ -577,63 +726,128 @@ async function runSplitServeWithWatch(context, tsxExecutable, tsxArgs, baseEnv,
     }
     logger.error('Watcher error:', error);
     logger.error('File watching failed; shutting down dev server.');
-    await shutdown('watcherError', 1);
+    await shutdown('watcherError', 1, 'watcher-error');
   }
 
-  const handleFileChange = async (reason, file) => {
-    if (pending) return;
-    pending = true;
-
+  /**
+   * Classify a file change event to determine which services need restarting
+   */
+  const classifyFileChange = (file, reason) => {
     // With cwd set, chokidar reports relative paths
-    // Our patterns are now relative, so match against the relative path
     const relativePath = path.isAbsolute(file) ? path.relative(root, file) : file;
 
-    // Determine which service(s) to restart
     let restartBackend = false;
     let restartFrontend = false;
+    let type = 'UNKNOWN';
 
     if (sharedMatcher && sharedMatcher(relativePath)) {
-      // Shared file changed - restart both
-      logger.info(`\n${'='.repeat(80)}`);
-      logger.info(`🔄 FILE CHANGE DETECTED: ${relativePath} (${reason})`);
-      logger.info(`   Type: SHARED - Will restart BOTH backend and frontend`);
-      logger.info('='.repeat(80));
       restartBackend = true;
       restartFrontend = true;
+      type = 'SHARED';
     } else if (backendMatcher && backendMatcher(relativePath)) {
-      // Backend file changed
-      logger.info(`\n${'='.repeat(80)}`);
-      logger.info(`🔄 FILE CHANGE DETECTED: ${relativePath} (${reason})`);
-      logger.info(`   Type: BACKEND - Will restart backend only`);
-      logger.info('='.repeat(80));
       restartBackend = true;
+      type = 'BACKEND';
     } else if (frontendMatcher && frontendMatcher(relativePath)) {
-      // Frontend file changed
-      logger.info(`\n${'='.repeat(80)}`);
-      logger.info(`🔄 FILE CHANGE DETECTED: ${relativePath} (${reason})`);
-      logger.info(`   Type: FRONTEND - Will restart frontend only`);
-      logger.info('='.repeat(80));
       restartFrontend = true;
+      type = 'FRONTEND';
     }
 
-    // Restart appropriate service(s)
-    if (restartBackend) {
-      await stopBackend();
-      await new Promise(r => setTimeout(r, 100)); // Small delay to ensure port release
-      startBackend();
-    }
-    if (restartFrontend) {
-      await stopFrontend();
-      await new Promise(r => setTimeout(r, 100)); // Small delay to ensure port release
-      startFrontend();
-    }
+    return { relativePath, reason, restartBackend, restartFrontend, type };
+  };
 
-    if (restartBackend || restartFrontend) {
-      logger.info(`✅ Restart complete\n`);
-    }
+  /**
+   * RxJS-based restart pipeline for backend
+   * Uses exhaustMap to ignore new requests while restarting
+   * Uses port verification to ensure clean restart (THE KEY FIX)
+   */
+  const setupBackendRestartPipeline = () => {
+    return backendRestartSubject.pipe(
+      takeUntil(shutdownSubject),
+      // exhaustMap ignores new restart requests while one is in progress
+      // This prevents restart-during-restart chaos
+      exhaustMap((change) => {
+        logger.info(`\n${'='.repeat(80)}`);
+        logger.info(`🔄 FILE CHANGE DETECTED: ${change.relativePath} (${change.reason})`);
+        logger.info(`   Type: ${change.type} - Restarting backend`);
+        logger.info('='.repeat(80));
+
+        return concat(
+          // Stop backend and WAIT for port to be verified free
+          stopBackendAndWait$(),
+          // Then start the new backend
+          of(undefined).pipe(
+            tap(() => {
+              startBackend();
+              logger.info(`✅ Backend restart complete\n`);
+            })
+          )
+        ).pipe(
+          catchError((err) => {
+            logger.error(`[BACKEND] Restart failed: ${err.message}`);
+            return of(undefined);
+          })
+        );
+      })
+    );
+  };
 
-    pending = false;
+  /**
+   * RxJS-based restart pipeline for frontend
+   * Uses exhaustMap to ignore new requests while restarting
+   * Uses port verification to ensure clean restart (THE KEY FIX)
+   */
+  const setupFrontendRestartPipeline = () => {
+    return frontendRestartSubject.pipe(
+      takeUntil(shutdownSubject),
+      // exhaustMap ignores new restart requests while one is in progress
+      exhaustMap((change) => {
+        logger.info(`\n${'='.repeat(80)}`);
+        logger.info(`🔄 FILE CHANGE DETECTED: ${change.relativePath} (${change.reason})`);
+        logger.info(`   Type: ${change.type} - Restarting frontend`);
+        logger.info('='.repeat(80));
+
+        return concat(
+          // Stop frontend and WAIT for port to be verified free
+          stopFrontendAndWait$(),
+          // Then start the new frontend
+          of(undefined).pipe(
+            tap(() => {
+              startFrontend();
+              logger.info(`✅ Frontend restart complete\n`);
+            })
+          )
+        ).pipe(
+          catchError((err) => {
+            logger.error(`[FRONTEND] Restart failed: ${err.message}`);
+            return of(undefined);
+          })
+        );
+      })
+    );
+  };
+
+  /**
+   * Handle file change event by routing to appropriate restart subject
+   */
+  const handleFileChange = (reason, file) => {
+    if (isShuttingDown) return;
+
+    const change = classifyFileChange(file, reason);
+
+    // Route to appropriate restart subject(s)
+    // The RxJS pipelines handle deduplication via exhaustMap
+    if (change.restartBackend) {
+      backendRestartSubject.next(change);
+    }
+    if (change.restartFrontend) {
+      frontendRestartSubject.next(change);
+    }
   };
+
+  // Set up RxJS restart pipelines
+  const backendRestartSub = setupBackendRestartPipeline().subscribe();
+  const frontendRestartSub = setupFrontendRestartPipeline().subscribe();
+  subscriptions.push(backendRestartSub, frontendRestartSub);
   
   // Create watcher
   // Use cwd with relative patterns for proper glob support
@@ -699,8 +913,8 @@ async function runSplitServeWithWatch(context, tsxExecutable, tsxArgs, baseEnv,
   await import(runtimeEntryPath);
 
   // Handle graceful shutdown signals
-  process.on('SIGINT', () => shutdown('SIGINT', 0));
-  process.on('SIGTERM', () => shutdown('SIGTERM', 0));
+  process.on('SIGINT', () => shutdown('SIGINT', 0, 'signal-handler'));
+  process.on('SIGTERM', () => shutdown('SIGTERM', 0, 'signal-handler'));
 
   // Handle process exit - this ensures children are killed even if parent crashes
   process.on('exit', () => {
@@ -717,13 +931,13 @@ async function runSplitServeWithWatch(context, tsxExecutable, tsxArgs, baseEnv,
   // Handle uncaught exceptions
   process.on('uncaughtException', async (error) => {
     logger.error('Uncaught exception:', error);
-    await shutdown('uncaughtException', 1);
+    await shutdown('uncaughtException', 1, 'uncaught-exception');
   });
 
   // Handle unhandled promise rejections
   process.on('unhandledRejection', async (reason, promise) => {
     logger.error('Unhandled rejection at:', promise, 'reason:', reason);
-    await shutdown('unhandledRejection', 1);
+    await shutdown('unhandledRejection', 1, 'unhandled-rejection');
   });
 
   // Keep process alive for file watching

package/src/runtime/runtime.js

@@ -97,12 +97,15 @@ async function setupProxyFirst(app, backendPort, config) {
         return resolve(cached.canHandle);
       }
 
+      // Configurable timeout - default 500ms is enough for GC pauses and startup
+      const checkTimeout = parseInt(process.env.NOEGO_BACKEND_CHECK_TIMEOUT) || 500;
+
       const options = {
         hostname: 'localhost',
         port: backendPort,
         path: pathname,
         method: 'GET',  // Use GET instead of HEAD since some backends don't support HEAD
-        timeout: 50,  // Very short timeout for dev mode
+        timeout: checkTimeout,
         headers: {
           'X-Proxy-Check': 'true'  // Indicate this is just a check
         }

package/src/utils/file-watcher-observable.js

@@ -0,0 +1,124 @@
+import { Observable, Subject, merge, fromEvent } from 'rxjs';
+import { map, takeUntil, share, finalize, debounceTime } from 'rxjs/operators';
+
+/**
+ * File event types emitted by the watcher observable
+ */
+export const FileEventType = {
+  ADD: 'add',
+  CHANGE: 'change',
+  UNLINK: 'unlink',
+  ADD_DIR: 'addDir',
+  UNLINK_DIR: 'unlinkDir',
+  READY: 'ready',
+  ERROR: 'error'
+};
+
+/**
+ * Convert a chokidar watcher instance to an RxJS Observable stream
+ * @param {FSWatcher} watcher - A chokidar watcher instance
+ * @returns {Observable<{type: string, path: string}>} - Observable of file events
+ */
+export function watcherToObservable(watcher) {
+  return new Observable((subscriber) => {
+    const handlers = {
+      add: (path) => subscriber.next({ type: FileEventType.ADD, path }),
+      change: (path) => subscriber.next({ type: FileEventType.CHANGE, path }),
+      unlink: (path) => subscriber.next({ type: FileEventType.UNLINK, path }),
+      addDir: (path) => subscriber.next({ type: FileEventType.ADD_DIR, path }),
+      unlinkDir: (path) => subscriber.next({ type: FileEventType.UNLINK_DIR, path }),
+      ready: () => subscriber.next({ type: FileEventType.READY, path: '' }),
+      error: (error) => subscriber.error(error)
+    };
+
+    // Attach event handlers
+    Object.entries(handlers).forEach(([event, handler]) => {
+      watcher.on(event, handler);
+    });
+
+    // Cleanup on unsubscription
+    return () => {
+      Object.entries(handlers).forEach(([event, handler]) => {
+        watcher.off(event, handler);
+      });
+    };
+  }).pipe(
+    // Share the observable so multiple subscribers don't create duplicate handlers
+    share()
+  );
+}
+
+/**
+ * Create a file change stream with classification capabilities
+ * @param {FSWatcher} watcher - A chokidar watcher instance
+ * @param {object} matchers - Object containing picomatch matchers for classification
+ * @param {Function} matchers.shared - Matcher for shared files (restart both)
+ * @param {Function} matchers.backend - Matcher for backend files
+ * @param {Function} matchers.frontend - Matcher for frontend files
+ * @returns {Observable<{type: string, path: string, restartBackend: boolean, restartFrontend: boolean}>}
+ */
+export function createClassifiedFileStream(watcher, matchers) {
+  return watcherToObservable(watcher).pipe(
+    // Filter to only file change events (not directories or ready)
+    map((event) => {
+      if (!event.path || event.type === FileEventType.READY ||
+          event.type === FileEventType.ADD_DIR || event.type === FileEventType.UNLINK_DIR) {
+        return null;
+      }
+
+      const { path } = event;
+      let restartBackend = false;
+      let restartFrontend = false;
+
+      // Check shared patterns first (restart both)
+      if (matchers.shared && matchers.shared(path)) {
+        restartBackend = true;
+        restartFrontend = true;
+      } else {
+        // Check individual patterns
+        if (matchers.backend && matchers.backend(path)) {
+          restartBackend = true;
+        }
+        if (matchers.frontend && matchers.frontend(path)) {
+          restartFrontend = true;
+        }
+      }
+
+      // Only return events that trigger restarts
+      if (!restartBackend && !restartFrontend) {
+        return null;
+      }
+
+      return {
+        ...event,
+        restartBackend,
+        restartFrontend
+      };
+    }),
+    // Filter out null events
+    map((event) => event) // This will pass through the filter in the pipe where it's used
+  );
+}
+
+/**
+ * Create a debounced file change stream
+ * Useful for batching rapid file changes
+ * @param {FSWatcher} watcher - A chokidar watcher instance
+ * @param {number} debounceMs - Debounce time in milliseconds (default: 50)
+ * @returns {Observable<{type: string, path: string}>}
+ */
+export function createDebouncedFileStream(watcher, debounceMs = 50) {
+  return watcherToObservable(watcher).pipe(
+    // Filter to only actual file events
+    map((event) => {
+      if (event.type === FileEventType.READY ||
+          event.type === FileEventType.ADD_DIR ||
+          event.type === FileEventType.UNLINK_DIR) {
+        return null;
+      }
+      return event;
+    }),
+    // Filter out nulls - this happens in the subscription
+    debounceTime(debounceMs)
+  );
+}

package/src/utils/port.js

@@ -0,0 +1,104 @@
+import { Observable, interval, of, throwError } from 'rxjs';
+import { map, switchMap, filter, take, timeout, catchError } from 'rxjs/operators';
+import net from 'node:net';
+
+/**
+ * Check if a port is currently free (available for binding)
+ * @param {number} port - The port number to check
+ * @returns {Observable<boolean>} - Observable that emits true if port is free, false if occupied
+ */
+export function checkPort(port) {
+  return new Observable((subscriber) => {
+    const server = net.createServer();
+
+    server.once('error', (err) => {
+      if (err.code === 'EADDRINUSE') {
+        // Port is in use
+        subscriber.next(false);
+        subscriber.complete();
+      } else {
+        subscriber.error(err);
+      }
+    });
+
+    server.once('listening', () => {
+      // Port is free - close the server and report success
+      server.close(() => {
+        subscriber.next(true);
+        subscriber.complete();
+      });
+    });
+
+    // Attempt to bind to the port
+    server.listen(port, '127.0.0.1');
+
+    // Cleanup on unsubscription
+    return () => {
+      try {
+        server.close();
+      } catch {
+        // Server may already be closed
+      }
+    };
+  });
+}
+
+/**
+ * Wait for a port to become free by polling at regular intervals
+ * @param {number} port - The port number to monitor
+ * @param {number} timeoutMs - Maximum time to wait in milliseconds (default: 5000)
+ * @param {number} pollInterval - Time between checks in milliseconds (default: 50)
+ * @returns {Observable<void>} - Observable that completes when port is free, errors on timeout
+ */
+export function waitForPortFree(port, timeoutMs = 5000, pollInterval = 50) {
+  return interval(pollInterval).pipe(
+    // Check port availability on each interval tick
+    switchMap(() => checkPort(port)),
+    // Only pass through when port is free
+    filter((isFree) => isFree === true),
+    // Complete after first confirmation that port is free
+    take(1),
+    // Map to void (we don't need the boolean value)
+    map(() => undefined),
+    // Timeout if port doesn't become free within the specified time
+    timeout({
+      each: timeoutMs,
+      with: () => throwError(() => new Error(`Port ${port} did not become free within ${timeoutMs}ms`))
+    }),
+    // Provide graceful fallback on timeout (continue anyway but log warning)
+    catchError((err) => {
+      console.warn(`[port.js] Warning: ${err.message}. Proceeding anyway.`);
+      return of(undefined);
+    })
+  );
+}
+
+/**
+ * Wait for a port to be in use (server started)
+ * @param {number} port - The port number to monitor
+ * @param {number} timeoutMs - Maximum time to wait in milliseconds (default: 10000)
+ * @param {number} pollInterval - Time between checks in milliseconds (default: 100)
+ * @returns {Observable<void>} - Observable that completes when port is in use, errors on timeout
+ */
+export function waitForPortInUse(port, timeoutMs = 10000, pollInterval = 100) {
+  return interval(pollInterval).pipe(
+    // Check port availability on each interval tick
+    switchMap(() => checkPort(port)),
+    // Only pass through when port is occupied (server running)
+    filter((isFree) => isFree === false),
+    // Complete after first confirmation that port is in use
+    take(1),
+    // Map to void
+    map(() => undefined),
+    // Timeout if server doesn't start within the specified time
+    timeout({
+      each: timeoutMs,
+      with: () => throwError(() => new Error(`Port ${port} did not become active within ${timeoutMs}ms`))
+    }),
+    // Provide graceful fallback on timeout
+    catchError((err) => {
+      console.warn(`[port.js] Warning: ${err.message}. Proceeding anyway.`);
+      return of(undefined);
+    })
+  );
+}

package/src/utils/process-observable.js

@@ -0,0 +1,218 @@
+import { Observable, of, timer, race, EMPTY } from 'rxjs';
+import { map, switchMap, take, catchError, finalize, tap } from 'rxjs/operators';
+import { spawn, execSync } from 'node:child_process';
+
+/**
+ * Process event types emitted by spawnProcess observable
+ */
+export const ProcessEvent = {
+  SPAWNED: 'spawned',
+  STDOUT: 'stdout',
+  STDERR: 'stderr',
+  EXITED: 'exited',
+  ERROR: 'error'
+};
+
+/**
+ * Kill a process and all its descendants (entire process tree)
+ * This ensures no orphaned processes remain when killing a parent
+ * @param {number} pid - Process ID to kill
+ * @param {string} signal - Signal to send (default: 'SIGKILL')
+ */
+export function killProcessTree(pid, signal = 'SIGKILL') {
+  if (!pid) return;
+
+  try {
+    // On Unix systems, use pkill to kill all descendants
+    if (process.platform !== 'win32') {
+      // Kill all child processes first
+      try {
+        execSync(`pkill -P ${pid}`, { stdio: 'ignore' });
+      } catch {
+        // No children or already dead, that's fine
+      }
+      // Then kill the parent
+      try {
+        process.kill(pid, signal);
+      } catch {
+        // Process may already be dead
+      }
+    } else {
+      // On Windows, use taskkill with /T flag to kill process tree
+      try {
+        execSync(`taskkill /pid ${pid} /T /F`, { stdio: 'ignore' });
+      } catch {
+        // Process may already be dead
+      }
+    }
+  } catch {
+    // Ignore errors - process might already be dead
+  }
+}
+
+/**
+ * Spawn a child process and return it as an Observable stream of events
+ * @param {string} command - The command to execute
+ * @param {string[]} args - Command arguments
+ * @param {object} options - Spawn options (cwd, env, etc.)
+ * @returns {Observable<{type: string, process?: ChildProcess, data?: any, code?: number, signal?: string}>}
+ */
+export function spawnProcess(command, args, options = {}) {
+  return new Observable((subscriber) => {
+    let proc = null;
+
+    try {
+      proc = spawn(command, args, {
+        ...options,
+        detached: false
+      });
+
+      // Emit spawned event with process reference
+      subscriber.next({
+        type: ProcessEvent.SPAWNED,
+        process: proc,
+        pid: proc.pid
+      });
+
+      // Handle stdout if not inherited
+      if (proc.stdout) {
+        proc.stdout.on('data', (data) => {
+          subscriber.next({
+            type: ProcessEvent.STDOUT,
+            data: data.toString()
+          });
+        });
+      }
+
+      // Handle stderr if not inherited
+      if (proc.stderr) {
+        proc.stderr.on('data', (data) => {
+          subscriber.next({
+            type: ProcessEvent.STDERR,
+            data: data.toString()
+          });
+        });
+      }
+
+      // Handle process exit
+      proc.on('exit', (code, signal) => {
+        subscriber.next({
+          type: ProcessEvent.EXITED,
+          code,
+          signal
+        });
+        subscriber.complete();
+      });
+
+      // Handle spawn errors
+      proc.on('error', (error) => {
+        subscriber.next({
+          type: ProcessEvent.ERROR,
+          error
+        });
+        subscriber.error(error);
+      });
+    } catch (error) {
+      subscriber.error(error);
+    }
+
+    // Cleanup on unsubscription
+    return () => {
+      if (proc && !proc.killed) {
+        try {
+          proc.kill('SIGTERM');
+        } catch {
+          // Process may already be dead
+        }
+      }
+    };
+  });
+}
+
+/**
+ * Stop a process gracefully with timeout-based force kill
+ * @param {ChildProcess} proc - The child process to stop
+ * @param {number} gracefulTimeout - Time to wait before force-killing (default: 5000ms)
+ * @param {function} killTreeFn - Function to kill process tree (optional, uses killProcessTree by default)
+ * @returns {Observable<void>} - Observable that completes when process has exited
+ */
+export function stopProcess(proc, gracefulTimeout = 5000, killTreeFn = killProcessTree) {
+  if (!proc || proc.killed) {
+    return of(undefined);
+  }
+
+  return new Observable((subscriber) => {
+    const pid = proc.pid;
+    let exited = false;
+    let forceKillTimer = null;
+
+    // Set up force kill timer
+    forceKillTimer = setTimeout(() => {
+      if (!exited && pid) {
+        console.warn(`[process-observable] Process ${pid} didn't exit gracefully, force killing...`);
+        killTreeFn(pid, 'SIGKILL');
+      }
+    }, gracefulTimeout);
+
+    // Listen for exit event
+    const onExit = () => {
+      exited = true;
+      if (forceKillTimer) {
+        clearTimeout(forceKillTimer);
+        forceKillTimer = null;
+      }
+      subscriber.next(undefined);
+      subscriber.complete();
+    };
+
+    proc.once('exit', onExit);
+
+    // Send SIGTERM to request graceful shutdown
+    try {
+      proc.kill('SIGTERM');
+    } catch {
+      // Process may already be dead
+      if (!exited) {
+        exited = true;
+        if (forceKillTimer) {
+          clearTimeout(forceKillTimer);
+          forceKillTimer = null;
+        }
+        subscriber.next(undefined);
+        subscriber.complete();
+      }
+    }
+
+    // Cleanup on unsubscription
+    return () => {
+      if (forceKillTimer) {
+        clearTimeout(forceKillTimer);
+      }
+      proc.off('exit', onExit);
+    };
+  });
+}
+
+/**
+ * Stop a process and verify it has completely stopped
+ * This is a higher-level function that combines stopProcess with verification
+ * @param {ChildProcess} proc - The child process to stop
+ * @param {number} gracefulTimeout - Time to wait before force-killing (default: 5000ms)
+ * @param {function} killTreeFn - Function to kill process tree
+ * @returns {Observable<void>} - Observable that completes when process is confirmed stopped
+ */
+export function stopProcessAndVerify(proc, gracefulTimeout = 5000, killTreeFn = killProcessTree) {
+  if (!proc || proc.killed) {
+    return of(undefined);
+  }
+
+  return stopProcess(proc, gracefulTimeout, killTreeFn).pipe(
+    // Add a small delay to ensure OS has released resources
+    switchMap(() => timer(50)),
+    map(() => undefined),
+    catchError((err) => {
+      console.warn(`[process-observable] Error stopping process: ${err.message}`);
+      return of(undefined);
+    })
+  );
+}