@geminilight/mindos 0.6.51 → 0.6.53

package/app/lib/config/panel-sizes.ts

@@ -0,0 +1,58 @@
+/**
+ * Centralized panel width configuration.
+ * All panel sizing constants in one place for easy maintenance.
+ */
+
+import type { PanelId } from '@/components/ActivityBar';
+
+// ── Left Panel (Files/Search/Agents/Echo/Discover) ──
+
+export const DEFAULT_LEFT_PANEL_WIDTH: Record<PanelId, number> = {
+  files: 280,
+  search: 320,
+  echo: 340,
+  agents: 300,
+  discover: 300,
+  workflows: 320,
+};
+
+export const LEFT_PANEL: { DEFAULT: number; MIN: number; MAX_RATIO: number; MAX_ABS: number } = {
+  DEFAULT: 280,
+  MIN: 240,
+  MAX_RATIO: 0.45, // 45% of screen width
+  MAX_ABS: 600, // Absolute pixel max
+};
+
+// ── Right Ask Panel ──
+
+export const RIGHT_ASK_PANEL: { DEFAULT: number; MIN: number; MAX_ABS: number; MIN_CONTENT: number } = {
+  DEFAULT: 420,
+  MIN: 400,
+  MAX_ABS: 4000, // Unlikely but safe upper bound
+  MIN_CONTENT: 360, // Minimum content width when panel is resized
+};
+
+// ── Right Agent Detail Panel ──
+
+export const RIGHT_AGENT_DETAIL_PANEL: { DEFAULT: number; MIN: number; MAX_ABS: number; MAX_RATIO: number } = {
+  DEFAULT: 400,
+  MIN: 300,
+  MAX_ABS: 640,
+  MAX_RATIO: 0.42, // 42% of screen width
+};
+
+// ── Mobile/Responsive Breakpoints ──
+
+export const RESPONSIVE_BREAKPOINTS = {
+  mobile: 375,
+  tablet: 768,
+  desktop: 1024,
+  wide: 1440,
+};
+
+// ── Activity Bar ──
+
+export const ACTIVITY_BAR = {
+  WIDTH_COLLAPSED: 48,
+  WIDTH_EXPANDED: 180,
+};

package/app/lib/hooks/useFocusTrap.ts

@@ -0,0 +1,65 @@
+'use client';
+
+import { useEffect, useRef } from 'react';
+
+/**
+ * Focus trap hook: keeps Tab navigation within a dialog/modal.
+ * Wraps focus from last focusable element back to first, and vice versa.
+ */
+export function useFocusTrap(ref: React.RefObject<HTMLElement | null>, enabled = true) {
+  useEffect(() => {
+    if (!enabled || !ref.current) return;
+
+    const handleKeyDown = (e: KeyboardEvent) => {
+      if (e.key !== 'Tab') return;
+
+      const focusableElements = ref.current?.querySelectorAll(
+        'button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])'
+      ) as NodeListOf<HTMLElement>;
+
+      if (!focusableElements || focusableElements.length === 0) return;
+
+      const firstElement = focusableElements[0];
+      const lastElement = focusableElements[focusableElements.length - 1];
+      const activeElement = document.activeElement;
+
+      if (e.shiftKey) {
+        // Shift+Tab on first element -> focus last
+        if (activeElement === firstElement) {
+          e.preventDefault();
+          lastElement.focus();
+        }
+      } else {
+        // Tab on last element -> focus first
+        if (activeElement === lastElement) {
+          e.preventDefault();
+          firstElement.focus();
+        }
+      }
+    };
+
+    const container = ref.current;
+    container.addEventListener('keydown', handleKeyDown);
+    return () => container.removeEventListener('keydown', handleKeyDown);
+  }, [ref, enabled]);
+}
+
+/**
+ * Return focus hook: saves reference to trigger element and restores focus on unmount
+ */
+export function useReturnFocus() {
+  const triggerRef = useRef<HTMLElement | null>(null);
+
+  const saveTrigger = (el: HTMLElement | null) => {
+    triggerRef.current = el;
+  };
+
+  useEffect(() => {
+    return () => {
+      // Return focus on unmount
+      triggerRef.current?.focus();
+    };
+  }, []);
+
+  return saveTrigger;
+}

package/app/lib/i18n/modules/ai-chat.ts

@@ -30,6 +30,10 @@ export const aiChatEn = {
     errorNoResponse: 'AI returned no content. Possible causes: model does not support streaming, proxy compatibility issue, or request exceeds context limit.',
     reconnecting: (attempt: number, max: number) => `Connection lost. Reconnecting (${attempt}/${max})...`,
     reconnectFailed: 'Connection failed after multiple attempts.',
+    proxyCompatMode: 'Using compatibility mode (non-streaming)...',
+    proxyCompatFailed: (err: string) => `Compatibility mode failed: ${err}. Please check your Base URL, API key, and model name.`,
+    proxyCompatDetecting: 'Detecting proxy compatibility, switching to non-streaming mode...',
+    proxyCompatAlsoFailed: (err: string) => `Compatibility mode also failed: ${err}. Please check your Base URL, API key, and model name.`,
     retry: 'Retry',
     suggestions: [
       'Summarize this document',
@@ -148,6 +152,10 @@ export const aiChatZh = {
     errorNoResponse: 'AI 未返回有效内容。可能原因：模型不支持流式输出、中转站兼容性问题、或请求超出上下文限制。',
     reconnecting: (attempt: number, max: number) => `连接中断，正在重连 (${attempt}/${max})...`,
     reconnectFailed: '多次重连失败，请检查网络后重试。',
+    proxyCompatMode: '正在以兼容模式调用...',
+    proxyCompatFailed: (err: string) => `兼容模式失败：${err}。请检查 Base URL、API Key 和模型名称。`,
+    proxyCompatDetecting: '正在检测接口兼容性，切换到兼容模式重试...',
+    proxyCompatAlsoFailed: (err: string) => `兼容模式也失败了：${err}。请检查 Base URL、API Key 和模型名称。`,
     retry: '重试',
     suggestions: [
       '总结这篇文档',

package/app/lib/i18n/modules/knowledge.ts

@@ -110,8 +110,8 @@ export const knowledgeEn = {
     dropOverlay: 'Drop to save to Capture',
     dropOverlayFormats: 'md · txt · pdf · csv · json',
     noMindRoot: 'Please configure your knowledge base first',
-    saveFailed: 'Failed to save files',
-    organizeFailed: 'Could not read files for organizing',
+    saveFailed: 'Failed to save files. Check disk space and permissions.',
+    organizeFailed: 'Could not read files for organizing. Check file permissions.',
   },
   pulse: {
     title: 'Your Agents',
@@ -162,7 +162,8 @@ export const knowledgeEn = {
     title: 'Pinned Files',
     addedToast: 'Added to Favorites',
     removedToast: 'Removed from Favorites',
-    empty: 'Pin files for quick access',
+    empty: 'No pinned files',
+    emptyHint: 'Click the star icon on any file to pin it here',
   },
   trash: {
     title: 'Trash',
@@ -182,6 +183,9 @@ export const knowledgeEn = {
     movedToTrash: 'Deleted',
     undo: 'Undo',
     undoFailed: 'Undo failed',
+    restoreFailed: 'Could not restore file. Check disk space and try again.',
+    deleteFailed: 'Could not permanently delete. Please try again.',
+    emptyFailed: 'Could not empty trash. Please try again.',
     emptied: (count: number) => `Emptied ${count} item${count !== 1 ? 's' : ''} from Trash`,
     restoreConflict: 'A file with this name already exists at the original location.',
     overwrite: 'Overwrite',
@@ -218,7 +222,7 @@ export const knowledgeEn = {
     downloadAgain: 'Download Again',
     fileCount: (n: number) => `${n} file${n !== 1 ? 's' : ''}`,
     downloaded: 'Downloaded',
-    error: 'Export failed',
+    error: 'Export failed. Please check disk space and try again.',
     retry: 'Retry',
   },
   fileImport: {
@@ -469,8 +473,8 @@ export const knowledgeZh = {
     dropOverlay: '拖放到暂存台快速保存',
     dropOverlayFormats: 'md · txt · pdf · csv · json',
     noMindRoot: '请先配置知识库路径',
-    saveFailed: '保存文件失败',
-    organizeFailed: '无法读取文件进行整理',
+    saveFailed: '保存文件失败，请检查磁盘空间和权限。',
+    organizeFailed: '无法读取文件进行整理，请检查文件权限。',
   },
   pulse: {
     title: '你的 Agent',
@@ -521,7 +525,8 @@ export const knowledgeZh = {
     title: '收藏文件',
     addedToast: '已添加到收藏',
     removedToast: '已取消收藏',
-    empty: '固定文件以快速访问',
+    empty: '还没有收藏文件',
+    emptyHint: '点击任何文件上的星标图标即可收藏',
   },
   trash: {
     title: '回收站',
@@ -541,6 +546,9 @@ export const knowledgeZh = {
     movedToTrash: '已删除',
     undo: '撤销',
     undoFailed: '撤销失败',
+    restoreFailed: '无法恢复文件，请检查磁盘空间后重试。',
+    deleteFailed: '无法彻底删除，请重试。',
+    emptyFailed: '无法清空回收站，请重试。',
     emptied: (count: number) => `已清空 ${count} 个项目`,
     restoreConflict: '原位置已有同名文件。',
     overwrite: '覆盖',
@@ -577,7 +585,7 @@ export const knowledgeZh = {
     downloadAgain: '再次下载',
     fileCount: (n: number) => `${n} 个文件`,
     downloaded: '已下载',
-    error: '导出失败',
+    error: '导出失败，请检查磁盘空间后重试。',
     retry: '重试',
   },
   fileImport: {

package/app/lib/i18n/modules/onboarding.ts

@@ -11,7 +11,7 @@ export const onboardingEn = {
     importHint: 'Already have notes? Set MIND_ROOT to your existing directory in Settings.',
     syncHint: 'Want cross-device sync? Run',
     syncHintSuffix: 'in the terminal after setup.',
-    initError: 'Initialization failed. Please try again.',
+    initError: 'Initialization failed. Please refresh the page or try a different template.',
     dismiss: 'Dismiss',
   },
   setup: {
@@ -233,7 +233,7 @@ export const onboardingZh = {
     importHint: '已有笔记？在设置中将 MIND_ROOT 指向已有目录即可。',
     syncHint: '需要跨设备同步？完成初始化后在终端运行',
     syncHintSuffix: '即可。',
-    initError: '初始化失败，请重试。',
+    initError: '初始化失败。请刷新页面或尝试其他模板。',
     dismiss: '关闭',
   },
   setup: {

package/app/lib/i18n/modules/settings.ts

@@ -12,6 +12,8 @@ export const settingsEn = {
       baseUrlHint: 'Optional. Use for proxies or custom API endpoints.',
       keyHint: 'Stored locally in ~/.mindos/config.json',
       keyOptionalHint: 'Optional for local providers. Stored in ~/.mindos/config.json',
+      keyChange: 'Change',
+      keyCancel: 'Cancel',
       envHint: 'Fields marked env have a value from environment variables. You can override them here, or restore all to env defaults.',
       envFieldNote: (key: string) => `Env var ${key} is set. Clear this field to fall back to it.`,
       resetToEnv: 'Reset to env value',
@@ -458,6 +460,8 @@ export const settingsZh = {
       envFieldNote: (key: string) => `环境变量 ${key} 已设置。清空此字段将回退到环境变量值。`,
       resetToEnv: '恢复为环境变量',
       restoreFromEnv: '从环境变量恢复',
+      keyChange: '更改',
+      keyCancel: '取消',
       noApiKey: 'API 密钥未设置，AI 功能暂不可用，请在此填写。',
       testKey: '测试',
       testKeyTesting: '测试中...',

package/app/lib/settings.ts

@@ -51,6 +51,8 @@ export interface ServerSettings {
   guideState?: GuideState;
   /** Per-agent ACP overrides (command, args, env, enabled). Keyed by agent ID. */
   acpAgents?: Record<string, import('./acp/agent-descriptors').AcpAgentOverride>;
+  /** Proxy compatibility cache: keyed by baseUrl, value is detected mode. */
+  baseUrlCompat?: Record<string, 'streaming' | 'non-streaming'>;
 }
 
 const DEFAULTS: ServerSettings = {
@@ -179,6 +181,15 @@ export function readSettings(): ServerSettings {
       setupPending: parsed.setupPending === true ? true : undefined,
       disabledSkills: Array.isArray(parsed.disabledSkills) ? parsed.disabledSkills as string[] : undefined,
       guideState: parseGuideState(parsed.guideState),
+      baseUrlCompat: (() => {
+        const raw = parsed.baseUrlCompat;
+        if (!raw || typeof raw !== 'object') return undefined;
+        const result: Record<string, 'streaming' | 'non-streaming'> = {};
+        for (const [k, v] of Object.entries(raw)) {
+          if (v === 'streaming' || v === 'non-streaming') result[k] = v;
+        }
+        return Object.keys(result).length > 0 ? result : undefined;
+      })(),
     };
   } catch {
     // Config file missing or corrupt → force setup wizard
@@ -206,6 +217,7 @@ export function writeSettings(settings: ServerSettings): void {
   if (settings.disabledSkills !== undefined) merged.disabledSkills = settings.disabledSkills;
   if (settings.guideState !== undefined) merged.guideState = settings.guideState;
   if (settings.acpAgents !== undefined) merged.acpAgents = settings.acpAgents;
+  if (settings.baseUrlCompat !== undefined) merged.baseUrlCompat = settings.baseUrlCompat;
   // setupPending: false/undefined → remove the field (cleanup); true → set it
   if ('setupPending' in settings) {
     if (settings.setupPending) merged.setupPending = true;
@@ -287,3 +299,23 @@ export function effectiveSopRoot(): string {
   const s = readSettings();
   return s.mindRoot || process.env.MIND_ROOT || path.join(os.homedir(), 'MindOS', 'mind');
 }
+
+/** Read the baseUrl → compat mode cache from config. Never throws. */
+export function readBaseUrlCompat(): Record<string, 'streaming' | 'non-streaming'> {
+  try {
+    const s = readSettings();
+    return s.baseUrlCompat ?? {};
+  } catch {
+    return {};
+  }
+}
+
+/** Persist a baseUrl compatibility detection result. Thread-safe via merge-write. */
+export function writeBaseUrlCompat(baseUrl: string, mode: 'streaming' | 'non-streaming'): void {
+  const s = readSettings();
+  const updated: Record<string, 'streaming' | 'non-streaming'> = {
+    ...(s.baseUrlCompat ?? {}),
+    [baseUrl]: mode,
+  };
+  writeSettings({ ...s, baseUrlCompat: updated });
+}

package/app/lib/stores/walkthrough-store.ts

@@ -21,7 +21,20 @@ export interface WalkthroughStoreState {
 
 /* ── Helpers ── */
 
+const LS_KEY = 'mindos_walkthrough_done';
+
+/**
+ * Persist walkthrough state to server AND localStorage.
+ * localStorage acts as a safety net: even if the server persist fails
+ * (e.g. during update restart, network blip), the completion state
+ * survives page reload and prevents the "stuck overlay" bug.
+ */
 function persistStep(step: number, dismissed: boolean) {
+  // Local safety net — instant, survives server outage
+  if (step >= walkthroughSteps.length || dismissed) {
+    try { localStorage.setItem(LS_KEY, '1'); } catch {}
+  }
+  // Server persist — fire-and-forget (localStorage is the safety net)
   fetch('/api/setup', {
     method: 'PATCH',
     headers: { 'Content-Type': 'application/json' },
@@ -31,6 +44,11 @@ function persistStep(step: number, dismissed: boolean) {
   }).catch((err) => { console.warn('[walkthrough-store] persist failed:', err); });
 }
 
+/** Check if walkthrough was completed/dismissed (fast, sync, local) */
+function isLocallyDone(): boolean {
+  try { return localStorage.getItem(LS_KEY) === '1'; } catch { return false; }
+}
+
 /* ── Store ── */
 
 export const useWalkthroughStore = create<WalkthroughStoreState>((set, get) => {
@@ -84,12 +102,26 @@ export const useWalkthroughStore = create<WalkthroughStoreState>((set, get) => {
       // Only auto-start on desktop
       if (window.innerWidth < 768) return () => {};
 
+      // Fast local check: if walkthrough was completed/dismissed, never reactivate.
+      // This prevents the "stuck overlay" bug where server persist failed during
+      // update restart but localStorage recorded the completion.
+      if (isLocallyDone()) return () => {};
+
       fetch('/api/setup')
         .then(r => r.json())
         .then(data => {
           const gs = data.guideState;
           if (!gs) return;
-          if (gs.walkthroughDismissed) return;
+          if (gs.walkthroughDismissed) {
+            try { localStorage.setItem(LS_KEY, '1'); } catch {} // sync local
+            return;
+          }
+
+          // If server says completed (step >= totalSteps), mark locally done
+          if (typeof gs.walkthroughStep === 'number' && gs.walkthroughStep >= totalSteps) {
+            try { localStorage.setItem(LS_KEY, '1'); } catch {};
+            return;
+          }
 
           if (gs.active && !gs.dismissed && gs.walkthroughStep === undefined) {
             if (isWelcome) {

package/bin/commands/update.js

@@ -15,6 +15,7 @@ import { EXIT } from '../lib/command.js';
 import { stopMindos } from '../lib/stop.js';
 import { getLocalIP } from '../lib/startup.js';
 import { isPortInUse } from '../lib/port.js';
+import { cleanEnvForRestart } from '../lib/clean-env.js';
 
 /**
  * Dynamically resolve the new ROOT after `npm install -g`.
@@ -180,7 +181,7 @@ export const run = async () => {
     const webPort = updateConfig.port ?? 3456;
     const mcpPort = updateConfig.mcpPort ?? 8781;
     console.log(dim('  (Waiting for Web UI to come back up — first run after update includes a rebuild...)'));
-    const ready = await gateway.waitForHttp(Number(webPort), { retries: 450, intervalMs: 2000, label: 'Web UI', logFile: LOG_PATH });
+    const ready = await gateway.waitForHttp(Number(webPort), { retries: 450, intervalMs: 2000, label: 'Web UI', logFile: LOG_PATH, expectedVersion: newVersion });
     if (ready) {
       const localIP = getLocalIP();
       console.log(`\n${'─'.repeat(53)}`);
@@ -214,13 +215,29 @@ export const run = async () => {
     if (wasRunning) {
       console.log(cyan('\n  MindOS is running — restarting to apply the new version...'));
       stopMindos();
-      // Wait for ports to free (up to 15s)
-      const deadline = Date.now() + 15_000;
+      // Wait for ports to free (up to 20s) with stabilization check.
+      // After first "free" reading, wait 1s and check again to avoid
+      // false negatives from TCP TIME_WAIT flickering.
+      const deadline = Date.now() + 20_000;
+      let portsFree = false;
       while (Date.now() < deadline) {
         const busy = await isPortInUse(webPort) || await isPortInUse(mcpPort);
-        if (!busy) break;
+        if (!busy) {
+          // Stabilization: wait 1s, then double-check
+          await new Promise((r) => setTimeout(r, 1000));
+          const stillFree = !(await isPortInUse(webPort)) && !(await isPortInUse(mcpPort));
+          if (stillFree) { portsFree = true; break; }
+        }
         await new Promise((r) => setTimeout(r, 500));
       }
+      if (!portsFree) {
+        console.log(yellow('  ⚠ Ports not fully released, force-killing remaining processes...'));
+        // Last resort: import killByPort and SIGKILL anything on these ports
+        const stopLib = await import('../lib/stop.js');
+        stopLib.killByPort(webPort);
+        stopLib.killByPort(mcpPort);
+        await new Promise((r) => setTimeout(r, 2000));
+      }
 
       // Stage 3: Rebuild
       writeUpdateStatus('rebuilding', vOpts);
@@ -237,12 +254,7 @@ export const run = async () => {
       // (`mindos start` has its own build-on-startup logic)
       writeUpdateStatus('restarting', vOpts);
       const newCliPath = resolve(updatedRoot, 'bin', 'cli.js');
-      const childEnv = { ...process.env };
-      delete childEnv.MINDOS_WEB_PORT;
-      delete childEnv.MINDOS_MCP_PORT;
-      delete childEnv.MIND_ROOT;
-      delete childEnv.AUTH_TOKEN;
-      delete childEnv.WEB_PASSWORD;
+      const childEnv = cleanEnvForRestart();
       const child = nodeSpawn(
         process.execPath, [newCliPath, 'start'],
         { detached: true, stdio: 'ignore', env: childEnv },
@@ -250,7 +262,7 @@ export const run = async () => {
       child.unref();
 
       console.log(dim('  (Waiting for Web UI to come back up...)'));
-      const ready = await gateway.waitForHttp(webPort, { retries: 180, intervalMs: 2000, label: 'Web UI', logFile: LOG_PATH });
+      const ready = await gateway.waitForHttp(webPort, { retries: 180, intervalMs: 2000, label: 'Web UI', logFile: LOG_PATH, expectedVersion: newVersion });
       if (ready) {
         const localIP = getLocalIP();
         console.log(`\n${'─'.repeat(53)}`);

package/bin/lib/clean-env.js

@@ -0,0 +1,38 @@
+/**
+ * Create a clean environment for spawning a new MindOS process.
+ *
+ * During `mindos update`, the old process inherits env vars like
+ * MINDOS_PROJECT_ROOT, MINDOS_CLI_PATH etc. that point to the OLD
+ * installation path. If these leak into the child process, the "new"
+ * server starts from the old code — the infamous "fake update" bug.
+ *
+ * This helper strips ALL MINDOS_*/MIND_* prefixed variables plus
+ * a curated denylist of other vars that can cause stale-path issues.
+ */
+
+/** Env var prefixes that must be stripped for a clean restart */
+const STRIP_PREFIXES = ['MINDOS_', 'MIND_'];
+
+/** Additional specific vars to strip (not prefix-matched) */
+const STRIP_EXACT = [
+  'AUTH_TOKEN',
+  'WEB_PASSWORD',
+  'NODE_OPTIONS', // may contain --inspect or old module paths
+];
+
+/**
+ * Return a copy of `process.env` with all MindOS-related vars removed.
+ * The new child process will re-derive paths from its own ROOT constant.
+ */
+export function cleanEnvForRestart(baseEnv = process.env) {
+  const cleaned = { ...baseEnv };
+  for (const key of Object.keys(cleaned)) {
+    if (STRIP_PREFIXES.some(p => key.startsWith(p))) {
+      delete cleaned[key];
+    }
+  }
+  for (const key of STRIP_EXACT) {
+    delete cleaned[key];
+  }
+  return cleaned;
+}

package/bin/lib/gateway.js

@@ -113,13 +113,43 @@ export function parseLogHint(line) {
   return null;
 }
 
-export async function waitForHttp(port, { retries = 60, intervalMs = 2000, label = 'service', logFile = null } = {}) {
+export async function waitForHttp(port, { retries = 60, intervalMs = 2000, label = 'service', logFile = null, expectedVersion = null } = {}) {
   const start = Date.now();
   const elapsed = () => {
     const s = Math.round((Date.now() - start) / 1000);
     return s < 60 ? `${s}s` : `${Math.floor(s / 60)}m${String(s % 60).padStart(2, '0')}s`;
   };
 
+  /**
+   * Version-aware readiness check: after health check passes, verify the
+   * server is actually running the expected version (not an orphaned old process).
+   * Prevents the "fake update" where health check hits a stale worker.
+   */
+  async function verifyVersion(hostname) {
+    if (!expectedVersion) return true; // no version check requested
+    try {
+      const { request } = await import('node:http');
+      return new Promise((resolve) => {
+        const req = request(
+          { hostname, port, path: '/api/update-check', method: 'GET', timeout: 5000 },
+          (res) => {
+            let body = '';
+            res.on('data', (chunk) => { body += chunk; });
+            res.on('end', () => {
+              try {
+                const data = JSON.parse(body);
+                resolve(data.current === expectedVersion);
+              } catch { resolve(false); }
+            });
+          }
+        );
+        req.on('error', () => resolve(false));
+        req.on('timeout', () => { req.destroy(); resolve(false); });
+        req.end();
+      });
+    } catch { return false; }
+  }
+
   // Track log file position for incremental reads
   let logOffset = 0;
   let lastHint = 'starting…';
@@ -169,9 +199,16 @@ export async function waitForHttp(port, { retries = 60, intervalMs = 2000, label
       });
       const ok = await tryHost('127.0.0.1') || await tryHost('localhost');
       if (ok) {
-        process.stdout.write(`\r\x1b[K`);
-        process.stdout.write(`  ${green('\u2714')} ${label} ready ${dim(`(${elapsed()})`)}\n`);
-        return true;
+        // If expectedVersion is set, verify the server is running the right version
+        const versionOk = await verifyVersion('127.0.0.1') || await verifyVersion('localhost');
+        if (!versionOk && expectedVersion) {
+          // Health check passed but wrong version — old process still serving
+          // Continue waiting for the new process to take over
+        } else {
+          process.stdout.write(`\r\x1b[K`);
+          process.stdout.write(`  ${green('\u2714')} ${label} ready ${dim(`(${elapsed()})`)}\n`);
+          return true;
+        }
       }
     } catch { /* not ready yet */ }
 

package/bin/lib/stop.js

@@ -4,6 +4,19 @@ import { green, yellow, dim } from './colors.js';
 import { loadPids, clearPids } from './pid.js';
 import { CONFIG_PATH } from './constants.js';
 
+/**
+ * Portable synchronous sleep using SharedArrayBuffer + Atomics.wait.
+ * Falls back to execSync('sleep N') on platforms without SharedArrayBuffer.
+ */
+function syncSleep(ms) {
+  try {
+    const sab = new SharedArrayBuffer(4);
+    Atomics.wait(new Int32Array(sab), 0, 0, ms);
+  } catch {
+    try { execSync(`sleep ${Math.ceil(ms / 1000)}`, { stdio: 'ignore' }); } catch {}
+  }
+}
+
 /**
  * Kill processes listening on the given port.
  * Tries lsof first, then falls back to parsing `ss` output.
@@ -52,6 +65,19 @@ export function killByPort(port) {
   for (const pid of pidsToKill) {
     try { process.kill(pid, 'SIGTERM'); killed++; } catch {}
   }
+
+  // SIGKILL fallback: if processes survive SIGTERM, force-kill after 2s.
+  // Next.js workers can ignore SIGTERM during request handling.
+  if (killed > 0) {
+    syncSleep(2000);
+    for (const pid of pidsToKill) {
+      try {
+        process.kill(pid, 0); // check if still alive
+        process.kill(pid, 'SIGKILL'); // force kill
+      } catch { /* already dead, good */ }
+    }
+  }
+
   return killed;
 }
 
@@ -60,10 +86,20 @@ export function killByPort(port) {
  */
 function killTree(pid) {
   // Try to kill the entire process group first
-  try { process.kill(-pid, 'SIGTERM'); return true; } catch {}
-  // Fallback: kill individual process
-  try { process.kill(pid, 'SIGTERM'); return true; } catch {}
-  return false;
+  try { process.kill(-pid, 'SIGTERM'); } catch {}
+  // Also kill individual process
+  try { process.kill(pid, 'SIGTERM'); } catch {}
+
+  // Wait briefly then SIGKILL if still alive
+  syncSleep(2000);
+
+  let alive = false;
+  try { process.kill(pid, 0); alive = true; } catch {}
+  if (alive) {
+    try { process.kill(-pid, 'SIGKILL'); } catch {}
+    try { process.kill(pid, 'SIGKILL'); } catch {}
+  }
+  return true;
 }
 
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geminilight/mindos",
-  "version": "0.6.51",
+  "version": "0.6.53",
   "description": "MindOS — Human-Agent Collaborative Mind System. Local-first knowledge base that syncs your mind to all AI Agents via MCP.",
   "keywords": [
     "mindos",