@geminilight/mindos 0.6.52 → 0.6.53

package/app/app/api/ask/route.ts

@@ -26,7 +26,8 @@ import { AGENT_SYSTEM_PROMPT, ORGANIZE_SYSTEM_PROMPT, CHAT_SYSTEM_PROMPT } from
 import type { AskModeApi } from '@/lib/types';
 import { toAgentMessages } from '@/lib/agent/to-agent-messages';
 import { logAgentOp } from '@/lib/agent/log';
-import { readSettings } from '@/lib/settings';
+import { readSettings, readBaseUrlCompat, writeBaseUrlCompat } from '@/lib/settings';
+import { en as i18nEn, zh as i18nZh } from '@/lib/i18n';
 import { MindOSError, apiError, ErrorCodes } from '@/lib/errors';
 import { metrics } from '@/lib/metrics';
 import { assertNotProtected } from '@/lib/core';
@@ -400,6 +401,134 @@ function toPiCustomToolDefinitions(tools: AgentTool<any>[]): ToolDefinition<any,
   }));
 }
 
+// ---------------------------------------------------------------------------
+// Non-streaming fallback for proxies that don't support stream + tools
+// ---------------------------------------------------------------------------
+
+/**
+ * Mini agent loop using non-streaming OpenAI-compatible API.
+ * Used when a proxy silently breaks stream+tools by returning plain text.
+ * Emits SSE events identical to the streaming path so the frontend is unaffected.
+ */
+async function runNonStreamingFallback(opts: {
+  baseUrl: string;
+  apiKey: string;
+  model: string;
+  systemPrompt: string;
+  historyMessages: { role: string; content: unknown }[];
+  userContent: string;
+  tools: AgentTool<any>[];
+  send: (event: MindOSSSEvent) => void;
+  signal: AbortSignal;
+  maxSteps: number;
+}): Promise<void> {
+  const { baseUrl, apiKey, model, systemPrompt, historyMessages, userContent, tools, send, signal, maxSteps } = opts;
+
+  const openaiTools = tools.map(t => ({
+    type: 'function' as const,
+    function: {
+      name: t.name,
+      description: t.description ?? '',
+      parameters: (t as any).parameters ?? { type: 'object', properties: {} },
+    },
+  }));
+
+  const messages: { role: string; content: unknown; tool_calls?: unknown; tool_call_id?: string }[] = [
+    { role: 'system', content: systemPrompt },
+    ...historyMessages,
+    { role: 'user', content: userContent },
+  ];
+
+  const toolMap = new Map(tools.map(t => [t.name, t]));
+  const endpoint = `${baseUrl.replace(/\/$/, '')}/chat/completions`;
+  let step = 0;
+
+  while (step < maxSteps) {
+    if (signal.aborted) throw new Error('Request aborted');
+    step++;
+
+    const resp = await fetch(endpoint, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'Authorization': `Bearer ${apiKey}`,
+      },
+      body: JSON.stringify({
+        model,
+        messages,
+        tools: openaiTools.length > 0 ? openaiTools : undefined,
+        tool_choice: openaiTools.length > 0 ? 'auto' : undefined,
+        stream: false,
+      }),
+      signal,
+    });
+
+    if (!resp.ok) {
+      const errText = await resp.text().catch(() => '');
+      throw new Error(`Non-streaming API error ${resp.status}: ${errText.slice(0, 200)}`);
+    }
+
+    const data = await resp.json() as any;
+    const choice = data?.choices?.[0];
+    if (!choice) throw new Error('Empty response from API');
+
+    const msg = choice.message;
+    const finishReason: string = choice.finish_reason ?? 'stop';
+
+    // Emit text content in chunks to simulate streaming appearance
+    if (msg.content) {
+      const text: string = typeof msg.content === 'string' ? msg.content : '';
+      if (text) {
+        const chunkSize = 40;
+        for (let i = 0; i < text.length; i += chunkSize) {
+          send({ type: 'text_delta', delta: text.slice(i, i + chunkSize) });
+          await new Promise(r => setTimeout(r, 8));
+        }
+      }
+    }
+
+    // No tool calls or naturally stopped → done
+    if (finishReason === 'stop' || !msg.tool_calls?.length) break;
+
+    // Execute each tool call
+    const toolResultMessages: { role: string; tool_call_id: string; content: string }[] = [];
+    for (const tc of msg.tool_calls) {
+      const toolName = tc.function?.name ?? '';
+      const toolCallId = tc.id ?? `call_${Date.now()}`;
+      let parsedArgs: Record<string, unknown> = {};
+      try { parsedArgs = JSON.parse(tc.function?.arguments ?? '{}'); } catch { /* ignore */ }
+
+      const tool = toolMap.get(toolName);
+      send({ type: 'tool_start', toolCallId, toolName, args: parsedArgs });
+
+      let resultText = '';
+      let isError = false;
+      if (tool) {
+        try {
+          const result = await tool.execute(toolCallId, parsedArgs, signal);
+          resultText = result.content
+            .filter((c: any) => c.type === 'text')
+            .map((c: any) => c.text)
+            .join('\n');
+        } catch (err) {
+          resultText = err instanceof Error ? err.message : String(err);
+          isError = true;
+        }
+      } else {
+        resultText = `Tool "${toolName}" not found`;
+        isError = true;
+      }
+
+      send({ type: 'tool_end', toolCallId, output: resultText, isError });
+      toolResultMessages.push({ role: 'tool', tool_call_id: toolCallId, content: resultText });
+    }
+
+    // Append assistant turn + tool results for next iteration
+    messages.push({ role: 'assistant', content: msg.content ?? null, tool_calls: msg.tool_calls });
+    messages.push(...toolResultMessages);
+  }
+}
+
 // ---------------------------------------------------------------------------
 // POST /api/ask
 // ---------------------------------------------------------------------------
@@ -433,6 +562,10 @@ export async function POST(req: NextRequest) {
   // Read agent config from settings
   const serverSettings = readSettings();
   const agentConfig = serverSettings.agent ?? {};
+
+  // Detect locale from Accept-Language header for i18n status messages
+  const acceptLang = req.headers.get('accept-language') ?? '';
+  const t = acceptLang.startsWith('zh') ? i18nZh.ask : i18nEn.ask;
   const defaultMaxSteps = askMode === 'chat' ? 8 : (agentConfig.maxSteps ?? 20);
   const stepLimit = Number.isFinite(body.maxSteps)
     ? Math.min(30, Math.max(1, Number(body.maxSteps)))
@@ -689,7 +822,7 @@ export async function POST(req: NextRequest) {
     const provOverride = body.providerOverride && isProviderId(body.providerOverride)
       ? body.providerOverride as ProviderId
       : undefined;
-    const { model, modelName, apiKey, provider } = getModelConfig({
+    const { model, modelName, apiKey, provider, baseUrl } = getModelConfig({
       provider: provOverride,
       hasImages: hasImages(messages),
     });
@@ -788,6 +921,7 @@ export async function POST(req: NextRequest) {
 
         let hasContent = false;
         let lastModelError = '';
+        const effectiveBaseUrlKey = baseUrl || 'default';
 
         session.subscribe((event: AgentEvent) => {
           if (isTextDeltaEvent(event)) {
@@ -993,6 +1127,36 @@ export async function POST(req: NextRequest) {
             safeClose();
           } else {
             // Route to MindOS agent (existing logic)
+
+            // ── Proxy compatibility check ──
+            // If this baseUrl is known to reject stream+tools, skip session.prompt() entirely
+            // and go straight to the non-streaming fallback path.
+            const compatCache = readBaseUrlCompat();
+            if (compatCache[effectiveBaseUrlKey] === 'non-streaming' && baseUrl && provider === 'openai') {
+              send({ type: 'status', message: t.proxyCompatMode });
+              try {
+                await runNonStreamingFallback({
+                  baseUrl,
+                  apiKey,
+                  model: modelName,
+                  systemPrompt,
+                  historyMessages: llmHistoryMessages,
+                  userContent: typeof lastUserContent === 'string' ? lastUserContent : JSON.stringify(lastUserContent),
+                  tools: requestTools,
+                  send,
+                  signal: req.signal,
+                  maxSteps: stepLimit,
+                });
+                metrics.recordRequest(Date.now() - requestStartTime);
+                send({ type: 'done' });
+              } catch (fallbackErr) {
+                metrics.recordRequest(Date.now() - requestStartTime);
+                send({ type: 'error', message: t.proxyCompatFailed(fallbackErr instanceof Error ? fallbackErr.message : String(fallbackErr)) });
+              }
+              safeClose();
+              return;
+            }
+
             // Retry with exponential backoff for transient failures (timeout, rate limit, 5xx).
             // Only retry if no content has been streamed yet — once the user sees partial
             // output, retrying would produce duplicate/garbled content.
@@ -1022,7 +1186,33 @@ export async function POST(req: NextRequest) {
 
             metrics.recordRequest(Date.now() - requestStartTime);
             if (!hasContent && lastModelError) {
-              send({ type: 'error', message: lastModelError });
+              // No content received — check if this looks like a proxy stream+tools incompatibility.
+              // Only attempt fallback for OpenAI-compatible endpoints with a custom baseUrl.
+              if (baseUrl && provider === 'openai') {
+                send({ type: 'status', message: t.proxyCompatDetecting });
+                try {
+                  await runNonStreamingFallback({
+                    baseUrl,
+                    apiKey,
+                    model: modelName,
+                    systemPrompt,
+                    historyMessages: llmHistoryMessages,
+                    userContent: typeof lastUserContent === 'string' ? lastUserContent : JSON.stringify(lastUserContent),
+                    tools: requestTools,
+                    send,
+                    signal: req.signal,
+                    maxSteps: stepLimit,
+                  });
+                  // Success → cache this endpoint as non-streaming so future requests skip the probe
+                  writeBaseUrlCompat(effectiveBaseUrlKey, 'non-streaming');
+                  console.log(`[ask] Proxy compat detected: ${effectiveBaseUrlKey} → non-streaming (cached)`);
+                  send({ type: 'done' });
+                } catch (fallbackErr) {
+                  send({ type: 'error', message: t.proxyCompatAlsoFailed(fallbackErr instanceof Error ? fallbackErr.message : String(fallbackErr)) });
+                }
+              } else {
+                send({ type: 'error', message: lastModelError });
+              }
             } else {
               send({ type: 'done' });
             }

package/app/app/api/restart/route.ts

@@ -3,31 +3,36 @@ import { NextResponse } from 'next/server';
 import { spawn } from 'node:child_process';
 import { resolve } from 'node:path';
 
+/**
+ * Strip ALL MINDOS_ and MIND_ prefixed env vars so the restart child
+ * process re-derives paths from its own installation root.
+ * Preserves old port values via MINDOS_OLD_ for cleanup.
+ */
+function cleanEnvForRestart(): { env: NodeJS.ProcessEnv; oldWebPort?: string; oldMcpPort?: string } {
+  const cleaned = { ...process.env };
+  const oldWebPort = cleaned.MINDOS_WEB_PORT;
+  const oldMcpPort = cleaned.MINDOS_MCP_PORT;
+  for (const key of Object.keys(cleaned)) {
+    if (key.startsWith('MINDOS_') || key.startsWith('MIND_')) {
+      delete cleaned[key];
+    }
+  }
+  delete cleaned.AUTH_TOKEN;
+  delete cleaned.WEB_PASSWORD;
+  delete cleaned.NODE_OPTIONS;
+  // Pass old ports so restart command can clean up stale listeners
+  if (oldWebPort) cleaned.MINDOS_OLD_WEB_PORT = oldWebPort;
+  if (oldMcpPort) cleaned.MINDOS_OLD_MCP_PORT = oldMcpPort;
+  return { env: cleaned, oldWebPort, oldMcpPort };
+}
+
 export async function POST() {
   try {
+    // Resolve CLI path BEFORE cleaning env (we still need current vars)
     const cliPath = process.env.MINDOS_CLI_PATH || resolve(process.env.MINDOS_PROJECT_ROOT || process.cwd(), '..', 'bin', 'cli.js');
     const nodeBin = process.env.MINDOS_NODE_BIN || process.execPath;
-    // Use 'restart' (stop all → wait for ports free → start) instead of bare
-    // 'start' which would fail assertPortFree because the current process and
-    // its MCP child are still holding the ports.
-    //
-    // IMPORTANT: Strip MINDOS_* env vars so the child's loadConfig() reads
-    // the *updated* config file instead of inheriting stale values from this
-    // process.  Without this, changing ports in the GUI has no effect on the
-    // restarted server — it would start on the old ports.
-    //
-    // Pass the current (old) ports via MINDOS_OLD_* so the restart command
-    // can clean up processes still listening on the previous ports.
-    const childEnv = { ...process.env };
-    const oldWebPort = childEnv.MINDOS_WEB_PORT;
-    const oldMcpPort = childEnv.MINDOS_MCP_PORT;
-    delete childEnv.MINDOS_WEB_PORT;
-    delete childEnv.MINDOS_MCP_PORT;
-    delete childEnv.MIND_ROOT;
-    delete childEnv.AUTH_TOKEN;
-    delete childEnv.WEB_PASSWORD;
-    if (oldWebPort) childEnv.MINDOS_OLD_WEB_PORT = oldWebPort;
-    if (oldMcpPort) childEnv.MINDOS_OLD_MCP_PORT = oldMcpPort;
+
+    const { env: childEnv } = cleanEnvForRestart();
     const child = spawn(nodeBin, [cliPath, 'restart'], {
       detached: true,
       stdio: 'ignore',

package/app/app/api/update/route.ts

@@ -3,25 +3,39 @@ import { NextResponse } from 'next/server';
 import { spawn } from 'node:child_process';
 import { resolve } from 'node:path';
 
+/**
+ * Strip ALL MINDOS_ and MIND_ prefixed env vars so the update child
+ * process re-derives paths from its own installation root after npm install.
+ * This prevents the "fake update" bug where the new process inherits
+ * stale MINDOS_PROJECT_ROOT / MINDOS_CLI_PATH pointing to old code.
+ */
+function cleanEnvForUpdate(): NodeJS.ProcessEnv {
+  const cleaned = { ...process.env };
+  for (const key of Object.keys(cleaned)) {
+    if (key.startsWith('MINDOS_') || key.startsWith('MIND_')) {
+      delete cleaned[key];
+    }
+  }
+  delete cleaned.AUTH_TOKEN;
+  delete cleaned.WEB_PASSWORD;
+  delete cleaned.NODE_OPTIONS;
+  return cleaned;
+}
+
 /**
  * POST /api/update — trigger `mindos update` as a detached child process.
  *
- * Similar to /api/restart: spawns the CLI command and returns immediately.
- * The update process will npm install, remove build stamp, and restart
- * the server. The current process will be killed during restart.
+ * Spawns the CLI command and returns immediately. The update process will
+ * npm install, remove build stamp, and restart the server.
+ * The current process will be killed during restart.
  */
 export async function POST() {
   try {
+    // Resolve CLI path BEFORE cleaning env (we still need current vars)
     const cliPath = process.env.MINDOS_CLI_PATH || resolve(process.env.MINDOS_PROJECT_ROOT || process.cwd(), '..', 'bin', 'cli.js');
     const nodeBin = process.env.MINDOS_NODE_BIN || process.execPath;
 
-    // Strip MINDOS_* env vars so the child reads fresh config
-    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 = cleanEnvForUpdate();
 
     const child = spawn(nodeBin, [cliPath, 'update'], {
       detached: true,

package/app/components/walkthrough/WalkthroughOverlay.tsx

@@ -2,7 +2,7 @@
 
 import { useState, useEffect, useCallback, useId } from 'react';
 import { useLocale } from '@/lib/stores/locale-store';
-import { useWalkthrough } from '@/lib/stores/walkthrough-store';
+import { useWalkthrough, useWalkthroughStore } from '@/lib/stores/walkthrough-store';
 import { walkthroughSteps } from './steps';
 import WalkthroughTooltip from './WalkthroughTooltip';
 
@@ -68,16 +68,31 @@ export default function WalkthroughOverlay() {
     return () => window.removeEventListener('keydown', handler, true);
   }, [skipFn]);
 
-  // If target element doesn't exist (e.g. Echo not enabled), auto-skip this step
+  // If target element doesn't exist (e.g. panel not enabled), auto-skip
+  // after a grace period. Use stable store ref to avoid re-triggering on
+  // every store change (which caused spurious skips during step transitions).
+  const currentStep = wt?.currentStep ?? 0;
   useEffect(() => {
     if (!step) return;
-    const el = document.querySelector(`[data-walkthrough="${step.anchor}"]`);
-    if (!el) {
-      // Target not in DOM — skip to next step after a brief delay
-      const timer = setTimeout(() => wt?.next(), 100);
-      return () => clearTimeout(timer);
-    }
-  }, [step, wt]);
+    // Wait 500ms for DOM to settle (sidebar animations, lazy rendering)
+    const timer = setTimeout(() => {
+      const el = document.querySelector(`[data-walkthrough="${step.anchor}"]`);
+      if (!el) {
+        useWalkthroughStore.getState().next();
+      }
+    }, 500);
+    return () => clearTimeout(timer);
+  // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [currentStep]); // Only re-run when step index changes, not on every store update
+
+  // Safety timeout: if overlay stays for 60s without user interaction, auto-dismiss.
+  // Prevents permanently stuck overlay from any unforeseen edge case.
+  useEffect(() => {
+    const timer = setTimeout(() => {
+      useWalkthroughStore.getState().skip();
+    }, 60_000);
+    return () => clearTimeout(timer);
+  }, [currentStep]); // Reset on each step change
 
   if (!wt || !step) return null;
 
@@ -138,7 +153,7 @@ export default function WalkthroughOverlay() {
         />
       </svg>
 
-      {/* Tooltip */}
+      {/* Tooltip — shown when target element found */}
       {targetRect && (
         <WalkthroughTooltip
           stepIndex={wt.currentStep}
@@ -146,6 +161,20 @@ export default function WalkthroughOverlay() {
           position={step.position}
         />
       )}
+
+      {/* Fallback dismiss button — shown when target element NOT found.
+          Without this, user sees dark overlay but no visible UI to dismiss it. */}
+      {!targetRect && (
+        <div className="fixed inset-0 z-[101] flex items-center justify-center pointer-events-none">
+          <button
+            onClick={wt.skip}
+            className="pointer-events-auto px-4 py-2 text-sm rounded-lg font-medium transition-all hover:opacity-90"
+            style={{ background: 'var(--amber)', color: 'var(--amber-foreground)' }}
+          >
+            {wt.currentStep === wt.totalSteps - 1 ? '✓' : '→'}
+          </button>
+        </div>
+      )}
     </>
   );
 }

package/app/lib/agent/model.ts

@@ -32,6 +32,7 @@ export function getModelConfig(options?: ModelConfigOverrides): {
   modelName: string;
   apiKey: string;
   provider: ProviderId;
+  baseUrl: string;
 } {
   const saved = effectiveAiConfig(options?.provider);
 
@@ -49,7 +50,7 @@ export function getModelConfig(options?: ModelConfigOverrides): {
     model = ensureVisionCapable(model);
   }
 
-  return { model, modelName, apiKey: cfg.apiKey, provider: cfg.provider };
+  return { model, modelName, apiKey: cfg.apiKey, provider: cfg.provider, baseUrl: cfg.baseUrl };
 }
 
 /**

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/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)}`);