@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 
-const { execFileSync } = require('child_process')
+const { spawn, execFileSync } = require('child_process')
 const { existsSync } = require('fs')
 const path = require('path')
 
@@ -48,15 +48,96 @@ if (!existsSync(binPath)) {
   process.exit(1)
 }
 
-try {
-  execFileSync(binPath, process.argv.slice(2), {
-    stdio: 'inherit',
-    env: process.env,
-  })
-  process.exit(0)
-} catch (e) {
-  if (e.signal) {
-    process.kill(process.pid, e.signal)
+// Run the binary as a CHILD we own, not a synchronous block, so we can forward
+// stop signals and — critically on Windows — tear down the WHOLE process tree.
+//
+// Why this matters: the binary runs in "router" mode and spawns one child
+// "worker" process per repo. Those workers hold a RocksDB lock AND keep the
+// `context-engine-rs.exe` image open. A worker only self-exits after an idle
+// window (default 300s), so if the router dies but its workers linger, the next
+// `npx vibervn-context-engine@latest` cannot replace the cached binary and npm
+// fails with `EPERM: operation not permitted, unlink ...context-engine-rs.exe`.
+//
+// On Windows there is no real SIGINT to forward: Node's `child.kill('SIGINT')`
+// maps to TerminateProcess, which kills ONLY the router and leaves the workers
+// orphaned. So on Windows we kill the whole tree with `taskkill /T /F` (the
+// router is still alive when we snapshot, so its workers are in the tree). On
+// POSIX we forward the real signal to the child, which the router handles to
+// kill its workers before exiting. The binary's Job Object (Windows
+// kill-on-close) remains the backstop for anything either path races past.
+const child = spawn(binPath, process.argv.slice(2), {
+  stdio: 'inherit',
+  env: process.env,
+})
+
+// Stop signals we forward / translate. Listed once so we can both register and
+// (in the exit handler) DE-register them — see the re-raise note below.
+const STOP_SIGNALS = ['SIGINT', 'SIGTERM', 'SIGHUP', 'SIGBREAK']
+
+let terminating = false
+let exited = false
+
+function terminate(signal) {
+  if (terminating) return
+  terminating = true
+
+  // Guard: if the child is already gone, do NOTHING. Two reasons:
+  //  - there is nothing left to kill, and
+  //  - on Windows `taskkill /T /F <pid>` against a dead PID could match a REUSED
+  //    pid and kill an unrelated process tree. `exited` is set by the 'exit'
+  //    handler; `child.exitCode !== null` also means it has exited; `child.pid`
+  //    is undefined if spawn never succeeded (the 'error' handler ran).
+  if (exited || child.exitCode !== null || child.pid === undefined) return
+
+  if (process.platform === 'win32') {
+    // Kill the router AND its worker children as one tree. /F so a worker that
+    // ignores the polite close still dies and releases the .exe + RocksDB lock.
+    // The child is still alive here (guarded above), so its workers are in the
+    // tree snapshot taskkill takes. Wrapped: a child that dies in the gap makes
+    // taskkill exit non-zero (execFileSync throws) — caught, then a best-effort
+    // direct kill (also caught) so the handler can never crash the wrapper.
+    try {
+      execFileSync('taskkill', ['/pid', String(child.pid), '/T', '/F'], {
+        stdio: 'ignore',
+      })
+    } catch {
+      try {
+        child.kill()
+      } catch {}
+    }
+  } else {
+    // POSIX: forward the real signal; the router kills its workers, then exits.
+    try {
+      child.kill(signal || 'SIGTERM')
+    } catch {}
   }
-  process.exit(e.status ?? 1)
 }
+
+// Forward the usual stop signals. SIGINT = Ctrl+C; SIGTERM = supervisor/kill;
+// SIGHUP = terminal closed (POSIX). Windows only delivers SIGINT/SIGBREAK here.
+// Each is registered exactly once; the `terminating` guard makes the body
+// idempotent if several arrive (or one arrives twice).
+for (const sig of STOP_SIGNALS) {
+  process.on(sig, () => terminate(sig))
+}
+
+child.on('error', (err) => {
+  console.error(`Failed to launch context-engine binary: ${err.message}`)
+  process.exit(1)
+})
+
+child.on('exit', (code, signal) => {
+  exited = true
+  if (signal) {
+    // Re-raise the signal on ourselves so our exit status reflects it, matching
+    // normal child-process signal semantics. We MUST drop our own signal
+    // listeners first: otherwise re-raising e.g. SIGINT would just re-enter
+    // `terminate()` (a no-op now, but it would also stop the default
+    // termination), leaving the wrapper hung instead of exiting. (Mostly a POSIX
+    // path — on Windows child death surfaces as an exit code, not a signal.)
+    for (const sig of STOP_SIGNALS) process.removeAllListeners(sig)
+    process.kill(process.pid, signal)
+    return
+  }
+  process.exit(code ?? 0)
+})
@@ -1,3 +1,4 @@
+use std::future::IntoFuture;
 use std::path::PathBuf;
 
 use clap::Parser;
@@ -254,7 +255,7 @@ async fn run_router(cli: &Cli, bind: &str) {
     // and the embedding/data dirs, but it does NOT start an IndexEngine or open
     // any repo DB — that is the whole point. `boot_router` loads settings and
     // resolves dirs only.
-    let app = match router::build_router_app(router::RouterBootOptions {
+    let (app, proxy) = match router::build_router_app(router::RouterBootOptions {
         data_dir: cli.data_dir.clone(),
         embeddings_dir: cli.embeddings_dir.clone(),
         bind: bind.to_owned(),
@@ -263,7 +264,7 @@ async fn run_router(cli: &Cli, bind: &str) {
     })
     .await
     {
-        Ok(app) => app,
+        Ok(pair) => pair,
         Err(e) => {
             eprintln!("error: {e:#}");
             std::process::exit(2);
@@ -278,8 +279,90 @@ async fn run_router(cli: &Cli, bind: &str) {
         });
 
     info!("Context Engine router listening on http://{addr}");
-    axum::serve(listener, app).await.unwrap_or_else(|e| {
-        eprintln!("router server error: {e}");
-        std::process::exit(1);
-    });
+
+    // Graceful stop: when a shutdown signal arrives, kill every live worker
+    // FIRST (releasing each worker's RocksDB LOCK + its hold on the binary image)
+    // and only then exit. Without this, the router would die but its
+    // idle-but-alive workers would keep running for up to `worker_idle_secs`
+    // (default 300s), pinning `context-engine-rs.exe` on Windows so a follow-up
+    // `npx ...@latest` cannot replace the cached binary (EPERM unlink).
+    //
+    // We RACE the server against the signal rather than using
+    // `with_graceful_shutdown` (which drains in-flight connections AFTER the
+    // signal): an idle SSE/keep-alive connection — e.g. a browser holding
+    // `/api/repos/:id/index-events` — would otherwise make Ctrl+C hang. The
+    // worker teardown is crash-safe (RocksDB LOCK releases on process exit;
+    // `file_meta` self-heals the next run), so a hard kill + immediate exit is
+    // the correct, responsive stop. `process::exit(0)` then drops the Job Object
+    // handle → kill-on-close catches any worker `kill_all` raced past (e.g. one
+    // mid-spawn). See `router::registry::Registry::kill_all` + `router::jobobject`.
+    //
+    // This deterministic teardown runs only on paths where the router actually
+    // receives the signal: `just rs-dev`, or launching the binary directly. On
+    // the npx path the Node wrapper hard-TERMINATES the router (Windows has no
+    // real SIGINT to forward), so this never runs there — that path is covered by
+    // the wrapper's `taskkill /T` over the whole tree plus the Job Object.
+    let server = axum::serve(listener, app).into_future();
+    tokio::select! {
+        res = server => {
+            res.unwrap_or_else(|e| {
+                eprintln!("router server error: {e}");
+                std::process::exit(1);
+            });
+        }
+        _ = shutdown_signal() => {
+            info!("shutdown signal received; killing live workers");
+            proxy.registry.kill_all().await;
+            info!("workers killed; router exiting");
+            std::process::exit(0);
+        }
+    }
+}
+
+/// Resolve once any OS stop signal arrives. On Windows we additionally wake on
+/// the console-close / logoff / shutdown control events (Ctrl+C alone does not
+/// cover a closed console window). On Unix we also wake on SIGTERM (the signal a
+/// supervisor/`kill` sends), not just Ctrl+C (SIGINT). First signal wins.
+async fn shutdown_signal() {
+    #[cfg(windows)]
+    {
+        use tokio::signal::windows;
+        // `ctrl_c` covers Ctrl+C; the others cover the console window being
+        // closed / the user logging off / the system shutting down. Any one of
+        // them should trigger the same orderly worker teardown.
+        let mut ctrl_close = match windows::ctrl_close() {
+            Ok(s) => s,
+            Err(_) => {
+                let _ = tokio::signal::ctrl_c().await;
+                return;
+            }
+        };
+        let mut ctrl_shutdown = windows::ctrl_shutdown().ok();
+        let mut ctrl_logoff = windows::ctrl_logoff().ok();
+        tokio::select! {
+            _ = tokio::signal::ctrl_c() => {}
+            _ = ctrl_close.recv() => {}
+            _ = async { match ctrl_shutdown.as_mut() { Some(s) => { s.recv().await; }, None => std::future::pending().await } } => {}
+            _ = async { match ctrl_logoff.as_mut() { Some(s) => { s.recv().await; }, None => std::future::pending().await } } => {}
+        }
+    }
+    #[cfg(unix)]
+    {
+        use tokio::signal::unix::{SignalKind, signal};
+        let mut term = match signal(SignalKind::terminate()) {
+            Ok(s) => s,
+            Err(_) => {
+                let _ = tokio::signal::ctrl_c().await;
+                return;
+            }
+        };
+        tokio::select! {
+            _ = tokio::signal::ctrl_c() => {}
+            _ = term.recv() => {}
+        }
+    }
+    #[cfg(not(any(windows, unix)))]
+    {
+        let _ = tokio::signal::ctrl_c().await;
+    }
 }
@@ -79,7 +79,12 @@ pub struct RouterState {
 
 /// Build the router-mode axum app: load settings + resolve dirs (NO IndexEngine,
 /// NO repo DB opens), create the Job Object, and wire global + proxy routes.
-pub async fn build_router_app(opts: RouterBootOptions) -> Result<Router> {
+///
+/// Returns the wired `Router` plus a clone of the [`ProxyCtx`] so the caller's
+/// shutdown handler can reach the worker [`registry::Registry`] (to kill live
+/// workers on Ctrl+C). The router's own `RouterState` keeps the original; the
+/// returned clone shares the same `Arc`-backed registry + Job Object.
+pub async fn build_router_app(opts: RouterBootOptions) -> Result<(Router, ProxyCtx)> {
     // The router does not open RocksDB, but a worker it spawns will — and the
     // worker reads these same env-derived bounds at its own boot. Setting them
     // here is harmless and keeps parity if the router is ever extended.
@@ -230,6 +235,11 @@ pub async fn build_router_app(opts: RouterBootOptions) -> Result<Router> {
         });
     }
 
+    // Clone the proxy context BEFORE `state` is moved into `.with_state(state)`
+    // below — the caller's shutdown handler needs it to reach the worker registry.
+    // Shares the same Arc-backed registry + Job Object as the router's state.
+    let proxy = state.proxy.clone();
+
     let app = Router::new()
         // ── Global endpoints served NATIVELY (no worker, no DB) ──────────────
         .route("/", get(serve_index))
@@ -305,7 +315,7 @@ pub async fn build_router_app(opts: RouterBootOptions) -> Result<Router> {
         // Global multi-repo `/mcp`: proxying handler (repo per call).
         .merge(Router::new().nest_service("/mcp", mcp_service));
 
-    Ok(app)
+    Ok((app, proxy))
 }
 
 // ── Native global handlers ──────────────────────────────────────────────────
 
@@ -350,6 +350,38 @@ impl Registry {
         }
     }
 
+    /// Kill EVERY live worker and block until each is reaped. Used by the
+    /// router's shutdown handler (Ctrl+C / SIGTERM / console-close) so a clean
+    /// stop releases every worker's RocksDB LOCK *and* its hold on the binary
+    /// image before the router exits — otherwise an idle-but-alive worker keeps
+    /// running for up to `worker_idle_secs` (default 300s) after the router is
+    /// gone, which on Windows pins `context-engine-rs.exe` and makes a follow-up
+    /// `npx ...@latest` fail to replace the cached binary (EPERM unlink).
+    ///
+    /// This is the DETERMINISTIC teardown for paths where the router actually
+    /// receives the signal (`just rs-dev`, running the binary directly). On the
+    /// npx path the Node wrapper hard-terminates the router (Windows has no real
+    /// SIGINT), so this handler may never run there — that path is covered by the
+    /// wrapper's `taskkill /T` (whole tree) plus the Job Object kill-on-close
+    /// backstop. Belt-and-suspenders: drain the map first so a concurrent
+    /// `acquire`/`reap` can't resurrect or double-reap an entry mid-shutdown.
+    pub async fn kill_all(&self) {
+        let entries: Vec<WorkerState> = {
+            let mut map = self.inner.write().await;
+            map.drain().map(|(_repo, state)| state).collect()
+        };
+        for state in entries {
+            if let WorkerState::Ready(w) = state {
+                let mut child = w.child.lock().await;
+                let _ = child.kill();
+                let _ = child.wait();
+            }
+            // `Spawning` holds no child handle here (the driver owns it until it
+            // publishes), so there is nothing to kill — the Job Object backstop
+            // covers a worker that was mid-spawn when shutdown hit.
+        }
+    }
+
     /// Snapshot of repos that currently have a Ready worker (for diagnostics /
     /// the router's "which repos are warm" view).
     pub async fn ready_repos(&self) -> Vec<String> {
@@ -666,8 +698,44 @@ mod tests {
         w.kill_and_wait().await; // cleanup
     }
 
-    /// (f) ABA SAFETY: the watchdog reaps a slow spawn's `Spawning(ready_A)`, a
-    /// waiter re-elects a fresh `Spawning(ready_B)`, then the original slow driver
+    /// (g) SHUTDOWN: `kill_all` terminates every live `Ready` worker and empties
+    /// the registry, so a clean router stop releases each worker's RocksDB LOCK +
+    /// its hold on the binary image (the EPERM-on-update root cause) instead of
+    /// leaving idle-but-alive workers running until their 300s idle timer fires.
+    #[tokio::test]
+    async fn kill_all_kills_live_workers_and_empties_registry() {
+        let reg = Registry::new();
+        let w1 = live_ready_worker();
+        let w2 = live_ready_worker();
+        install_ready(&reg, "repoK1", w1.clone()).await;
+        install_ready(&reg, "repoK2", w2.clone()).await;
+
+        reg.kill_all().await;
+
+        // Registry is fully drained.
+        assert!(
+            reg.ready_repos().await.is_empty() && reg.spawning_repos().await.is_empty(),
+            "kill_all must drain every entry"
+        );
+        // Both children are actually dead: try_wait reports an exit status.
+        for w in [&w1, &w2] {
+            let mut child = w.child.lock().await;
+            assert!(
+                matches!(child.try_wait(), Ok(Some(_))),
+                "kill_all must have killed + reaped the worker child"
+            );
+        }
+    }
+
+    /// (g') `kill_all` on an empty registry is a no-op (idempotent / safe to call
+    /// even when no workers ever spawned).
+    #[tokio::test]
+    async fn kill_all_on_empty_registry_is_noop() {
+        let reg = Registry::new();
+        reg.kill_all().await;
+        assert!(reg.ready_repos().await.is_empty());
+    }
+
     /// finally completes. `publish_ready(ready_A)` must report SUPERSEDED (false)
     /// and must NOT clobber `ready_B` into `Ready` (that would leave two workers
     /// racing one LOCK). The re-elected `Spawning(ready_B)` stays intact.
 
@@ -74,7 +74,8 @@ async fn start_router(home: &TempDir) -> SocketAddr {
         worker_exe: Some(worker_exe()),
     })
     .await
-    .expect("router app");
+    .expect("router app")
+    .0;
     tokio::spawn(async move {
         axum::serve(listener, app).await.expect("serve");
     });
 
@@ -43,7 +43,8 @@ async fn start_router(home: &TempDir) -> SocketAddr {
         worker_exe: None,
     })
     .await
-    .expect("router app builds");
+    .expect("router app builds")
+    .0;
     tokio::spawn(async move {
         axum::serve(listener, app).await.expect("router serve");
     });