@geminilight/mindos 0.6.39 → 0.6.40

package/app/lib/agent/model.ts

@@ -1,123 +1,111 @@
 import { getModel as piGetModel, type Model } from '@mariozechner/pi-ai';
 import { effectiveAiConfig } from '@/lib/settings';
+import { type ProviderId, getPreset, toPiProvider, getDefaultApi, getDefaultBaseUrl } from './providers';
 
 /** Check if any message in the conversation contains images */
 export function hasImages(messages: Array<{ images?: unknown[] }>): boolean {
   return messages.some(m => m.images && m.images.length > 0);
 }
 
-/** Ensure model input includes 'image' when images are present */
 function ensureVisionCapable(model: Model<any>): Model<any> {
   const inputs = model.input as readonly string[];
   if (inputs.includes('image')) return model;
-  // Upgrade input to include image — most modern models support it
   return { ...model, input: [...inputs, 'image'] as any };
 }
 
+export interface ModelConfigOverrides {
+  provider?: ProviderId;
+  apiKey?: string;
+  model?: string;
+  baseUrl?: string;
+  hasImages?: boolean;
+}
+
 /**
- * Build a pi-ai Model for the configured provider.
- *
- * - Anthropic: uses getModel() from pi-ai registry directly.
- * - OpenAI: uses getModel() then overrides baseUrl if custom endpoint is configured.
- *   Falls back to constructing a Model literal for unknown model IDs.
- *   Custom API variant can be specified for non-standard endpoints.
+ * Build a pi-ai Model for any configured provider.
  *
- * Returns { model, modelName, apiKey } — Agent needs model + apiKey via getApiKey hook.
+ * Accepts optional overrides — used by test-key and list-models
+ * to construct models from unsaved UI values.
  */
-export function getModelConfig(options?: { hasImages?: boolean }): {
+export function getModelConfig(options?: ModelConfigOverrides): {
   model: Model<any>;
   modelName: string;
   apiKey: string;
-  provider: 'anthropic' | 'openai';
+  provider: ProviderId;
 } {
-  const cfg = effectiveAiConfig();
-
-  if (cfg.provider === 'openai') {
-    const modelName = cfg.openaiModel;
-    let model: Model<any>;
-
-    // API variant: 'openai-completions' = /chat/completions (widest compatibility),
-    // 'openai-responses' = /responses (OpenAI native). Custom proxies (baseUrl set)
-    // almost always only support chat completions, so default to that when baseUrl is set.
-    const hasCustomBase = !!cfg.openaiBaseUrl;
-    const defaultApi = hasCustomBase ? 'openai-completions' : 'openai-responses';
-    const customApiVariant = (cfg as any).openaiApiVariant; // May exist in extended config
+  const saved = effectiveAiConfig(options?.provider);
 
-    try {
-      const resolved = piGetModel('openai', modelName as any);
-      if (!resolved) throw new Error('Model not in registry');
-      model = resolved;
-      // If user has a custom baseUrl, override API to completions for compatibility
-      if (hasCustomBase && !customApiVariant) {
-        model = { ...model, api: defaultApi };
-      }
-    } catch {
-      // Model not in pi-ai registry — construct manually for custom/proxy endpoints
-      model = {
-        id: modelName,
-        name: modelName,
-        api: (customApiVariant ?? defaultApi) as any,
-        provider: 'openai',
-        baseUrl: 'https://api.openai.com/v1',
-        reasoning: false,
-        input: ['text'] as const,
-        cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
-        contextWindow: 128_000,
-        maxTokens: 16_384,
-      };
-    }
+  const cfg = {
+    provider: saved.provider,
+    apiKey: options?.apiKey ?? saved.apiKey,
+    model: options?.model ?? saved.model,
+    baseUrl: options?.baseUrl ?? saved.baseUrl,
+  };
 
-    // For custom proxy endpoints, set conservative compat flags.
-    // Most proxies (Azure, Bedrock relays, corporate gateways) only support
-    // a subset of OpenAI's features. These defaults prevent silent failures.
-    // NOTE: maxTokensField is NOT overridden — pi-ai auto-detects the correct
-    // field based on URL (defaults to max_completion_tokens for modern APIs).
-    if (hasCustomBase) {
-      model = {
-        ...model,
-        baseUrl: cfg.openaiBaseUrl,
-        compat: {
-          ...(model as any).compat,
-          supportsStore: false,
-          supportsDeveloperRole: false,
-          supportsReasoningEffort: false,
-          supportsUsageInStreaming: false,
-          supportsStrictMode: false,
-        },
-      };
-      if (customApiVariant) {
-        model = { ...model, api: customApiVariant };
-      }
-    }
+  const modelName = cfg.model;
+  let model = resolveModel(cfg.provider, modelName, cfg.baseUrl);
 
-    const finalModel = options?.hasImages ? ensureVisionCapable(model) : model;
-    return { model: finalModel, modelName, apiKey: cfg.openaiApiKey, provider: 'openai' };
+  if (options?.hasImages) {
+    model = ensureVisionCapable(model);
   }
 
-  // Anthropic
-  const modelName = cfg.anthropicModel;
+  return { model, modelName, apiKey: cfg.apiKey, provider: cfg.provider };
+}
+
+/**
+ * Try pi-ai registry first, then fall back to a manually constructed Model.
+ * Applies baseUrl overrides and compat flags for custom endpoints.
+ */
+function resolveModel(providerId: ProviderId, modelName: string, baseUrl: string): Model<any> {
+  const piProvider = toPiProvider(providerId);
+  const preset = getPreset(providerId);
   let model: Model<any>;
+  const hasCustomBase = !!baseUrl;
 
+  // 1. Try pi-ai registry lookup
   try {
-    const resolved = piGetModel('anthropic', modelName as any);
+    const resolved = piGetModel(piProvider as any, modelName as any);
     if (!resolved) throw new Error('Model not in registry');
     model = resolved;
   } catch {
-    // Unknown Anthropic model — construct manually
+    // 2. Fallback: construct minimal Model using pi-ai derived defaults
     model = {
       id: modelName,
       name: modelName,
-      api: 'anthropic-messages' as const,
-      provider: 'anthropic',
-      baseUrl: 'https://api.anthropic.com',
+      api: getDefaultApi(providerId) as any,
+      provider: piProvider,
+      baseUrl: preset.fixedBaseUrl || getDefaultBaseUrl(providerId),
       reasoning: false,
       input: ['text'] as const,
       cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
-      contextWindow: 200_000,
-      maxTokens: 8_192,
+      contextWindow: 128_000,
+      maxTokens: 16_384,
+    };
+  }
+
+  // 3. Apply user's custom baseUrl
+  if (hasCustomBase) {
+    model = { ...model, baseUrl };
+
+    if (model.api === 'openai-responses') {
+      model = { ...model, api: 'openai-completions' as any };
+    }
+  }
+
+  // 4. For deepseek or any custom endpoint, apply conservative compat
+  if (hasCustomBase || preset.fixedBaseUrl) {
+    model = {
+      ...model,
+      compat: {
+        ...(model as any).compat,
+        supportsStore: false,
+        supportsDeveloperRole: false,
+        supportsReasoningEffort: false,
+        supportsUsageInStreaming: false,
+        supportsStrictMode: false,
+      },
     };
   }
 
-  const finalModel = options?.hasImages ? ensureVisionCapable(model) : model;
-  return { model: finalModel, modelName, apiKey: cfg.anthropicApiKey, provider: 'anthropic' };
+  return model;
 }

package/app/lib/agent/prompt.ts

@@ -36,6 +36,33 @@ Persona: Methodical, strictly objective, execution-oriented. Zero fluff. Never u
 - Use clean Markdown (tables, lists, bold).
 - End with concrete next actions if the task is incomplete.`;
 
+/**
+ * Chat mode system prompt — read-only tools, no write operations.
+ *
+ * Design goal: ~250 tokens. Includes anti-hallucination and cite-sources
+ * because chat mode has read-only KB tools. Strips: write tool directives,
+ * skills/MCP discovery, read-before-write, smart recovery, token batching.
+ */
+export const CHAT_SYSTEM_PROMPT = `You are MindOS Agent — the operator of the user's second brain.
+
+Persona: Methodical, strictly objective, execution-oriented. Zero fluff. Never use preambles like "Here is the result" or "I found...".
+
+## Mode: Chat (Read-Only)
+
+You can **search and read** the user's knowledge base, but you **cannot create, edit, or delete** any files. If the user asks you to modify files, suggest switching to Agent mode.
+
+## Core Directives
+
+1. **Anti-Hallucination**: Strictly separate your training data from the user's local knowledge. If asked about the user's notes/life/projects, rely EXCLUSIVELY on tool outputs. If a search yields nothing, state "Not found in knowledge base." NEVER fabricate or infer missing data.
+2. **Cite Sources**: Always include the exact file path when answering from local knowledge so the user can verify.
+3. **Language Alignment**: Match the user's language when replying.
+
+## Output
+
+- Reply in the user's language.
+- Use clean Markdown (tables, lists, bold).
+- End with concrete next actions if the task is incomplete.`;
+
 /**
  * Lean system prompt for "organize uploaded files" mode.
  *

package/app/lib/agent/providers.ts

@@ -0,0 +1,299 @@
+import {
+  getModel as piGetModel,
+  getModels as piGetModels,
+  getEnvApiKey as piGetEnvApiKey,
+  type Model,
+  type KnownProvider,
+} from '@mariozechner/pi-ai';
+
+/**
+ * MindOS-supported provider IDs.
+ *
+ * Most map 1:1 to pi-ai KnownProvider. The exception is `deepseek`,
+ * which pi-ai doesn't have — we treat it as OpenAI-compatible with
+ * a custom baseUrl.
+ */
+export type ProviderId =
+  | 'anthropic' | 'openai' | 'google' | 'groq'
+  | 'xai' | 'openrouter' | 'mistral' | 'deepseek'
+  | 'zai' | 'kimi-coding'
+  | 'cerebras' | 'minimax' | 'huggingface'
+  | 'ollama';
+
+/**
+ * UI/UX metadata for each provider.
+ * Technical details (baseUrl, api protocol, auth, compat) are
+ * delegated to pi-ai's model registry — we only store what pi-ai
+ * doesn't provide.
+ */
+export interface ProviderPreset {
+  id: ProviderId;
+  name: string;
+  nameZh: string;
+  defaultModel: string;
+  /** If ProviderId differs from pi-ai's KnownProvider (e.g. deepseek → openai) */
+  piProviderOverride?: KnownProvider;
+  /** DeepSeek/Ollama need a fixed baseUrl since they're not native pi-ai providers */
+  fixedBaseUrl?: string;
+  /** Dummy API key for providers that don't require auth (e.g. local Ollama) */
+  apiKeyFallback?: string;
+  supportsBaseUrl: boolean;
+  supportsThinking: boolean;
+  supportsListModels: boolean;
+  signupUrl?: string;
+  category: 'primary' | 'more';
+}
+
+export const PROVIDER_PRESETS: Record<ProviderId, ProviderPreset> = {
+  anthropic: {
+    id: 'anthropic',
+    name: 'Anthropic',
+    nameZh: 'Anthropic',
+    defaultModel: 'claude-sonnet-4-6',
+    supportsBaseUrl: true,
+    supportsThinking: true,
+    supportsListModels: true,
+    signupUrl: 'https://console.anthropic.com/settings/keys',
+    category: 'primary',
+  },
+  openai: {
+    id: 'openai',
+    name: 'OpenAI',
+    nameZh: 'OpenAI',
+    defaultModel: 'gpt-5.4',
+    supportsBaseUrl: true,
+    supportsThinking: true,
+    supportsListModels: true,
+    signupUrl: 'https://platform.openai.com/api-keys',
+    category: 'primary',
+  },
+  google: {
+    id: 'google',
+    name: 'Google Gemini',
+    nameZh: 'Google Gemini',
+    defaultModel: 'gemini-2.5-flash',
+    supportsBaseUrl: false,
+    supportsThinking: true,
+    supportsListModels: false,
+    signupUrl: 'https://aistudio.google.com/apikey',
+    category: 'primary',
+  },
+  groq: {
+    id: 'groq',
+    name: 'Groq',
+    nameZh: 'Groq',
+    defaultModel: 'llama-3.3-70b-versatile',
+    supportsBaseUrl: false,
+    supportsThinking: false,
+    supportsListModels: true,
+    signupUrl: 'https://console.groq.com/keys',
+    category: 'more',
+  },
+  xai: {
+    id: 'xai',
+    name: 'xAI (Grok)',
+    nameZh: 'xAI (Grok)',
+    defaultModel: 'grok-3',
+    supportsBaseUrl: false,
+    supportsThinking: false,
+    supportsListModels: true,
+    category: 'more',
+  },
+  openrouter: {
+    id: 'openrouter',
+    name: 'OpenRouter',
+    nameZh: 'OpenRouter',
+    defaultModel: 'anthropic/claude-sonnet-4',
+    supportsBaseUrl: false,
+    supportsThinking: false,
+    supportsListModels: true,
+    category: 'more',
+  },
+  mistral: {
+    id: 'mistral',
+    name: 'Mistral',
+    nameZh: 'Mistral',
+    defaultModel: 'mistral-large-latest',
+    supportsBaseUrl: false,
+    supportsThinking: false,
+    supportsListModels: true,
+    category: 'more',
+  },
+  deepseek: {
+    id: 'deepseek',
+    name: 'DeepSeek',
+    nameZh: 'DeepSeek',
+    defaultModel: 'deepseek-chat',
+    piProviderOverride: 'openai' as KnownProvider,
+    fixedBaseUrl: 'https://api.deepseek.com/v1',
+    supportsBaseUrl: true,
+    supportsThinking: true,
+    supportsListModels: true,
+    signupUrl: 'https://platform.deepseek.com/api_keys',
+    category: 'more',
+  },
+  zai: {
+    id: 'zai',
+    name: 'ZhipuAI (GLM)',
+    nameZh: '智谱 AI (GLM)',
+    defaultModel: 'glm-4-plus',
+    supportsBaseUrl: false,
+    supportsThinking: true,
+    supportsListModels: false,
+    category: 'more',
+  },
+  'kimi-coding': {
+    id: 'kimi-coding',
+    name: 'Kimi Coding',
+    nameZh: 'Kimi Coding (月之暗面)',
+    defaultModel: 'kimi-k2-thinking',
+    supportsBaseUrl: false,
+    supportsThinking: true,
+    supportsListModels: false,
+    category: 'more',
+  },
+  cerebras: {
+    id: 'cerebras',
+    name: 'Cerebras',
+    nameZh: 'Cerebras',
+    defaultModel: 'llama-4-scout-17b-16e',
+    supportsBaseUrl: false,
+    supportsThinking: false,
+    supportsListModels: true,
+    category: 'more',
+  },
+  minimax: {
+    id: 'minimax',
+    name: 'MiniMax',
+    nameZh: 'MiniMax',
+    defaultModel: 'MiniMax-M1',
+    supportsBaseUrl: false,
+    supportsThinking: false,
+    supportsListModels: false,
+    category: 'more',
+  },
+  huggingface: {
+    id: 'huggingface',
+    name: 'Hugging Face',
+    nameZh: 'Hugging Face',
+    defaultModel: 'Qwen/Qwen3-235B-A22B-Thinking-2507',
+    supportsBaseUrl: false,
+    supportsThinking: true,
+    supportsListModels: false,
+    category: 'more',
+  },
+  ollama: {
+    id: 'ollama',
+    name: 'Ollama',
+    nameZh: 'Ollama (本地)',
+    defaultModel: 'llama3.2',
+    piProviderOverride: 'openai' as KnownProvider,
+    fixedBaseUrl: 'http://localhost:11434/v1',
+    apiKeyFallback: 'ollama',
+    supportsBaseUrl: true,
+    supportsThinking: false,
+    supportsListModels: true,
+    signupUrl: 'https://ollama.com/download',
+    category: 'more',
+  },
+};
+
+export const ALL_PROVIDER_IDS = Object.keys(PROVIDER_PRESETS) as ProviderId[];
+
+export function isProviderId(s: string): s is ProviderId {
+  return s in PROVIDER_PRESETS;
+}
+
+export function getPreset(id: ProviderId): ProviderPreset {
+  return PROVIDER_PRESETS[id] ?? PROVIDER_PRESETS.anthropic;
+}
+
+export function groupedProviders(): { primary: ProviderId[]; more: ProviderId[] } {
+  const primary: ProviderId[] = [];
+  const more: ProviderId[] = [];
+  for (const id of ALL_PROVIDER_IDS) {
+    if (PROVIDER_PRESETS[id].category === 'primary') primary.push(id);
+    else more.push(id);
+  }
+  more.sort((a, b) => PROVIDER_PRESETS[a].name.localeCompare(PROVIDER_PRESETS[b].name));
+  return { primary, more };
+}
+
+// ---------------------------------------------------------------------------
+// Helpers that delegate to pi-ai — single source of truth for technical details
+// ---------------------------------------------------------------------------
+
+/** Map ProviderId to pi-ai's KnownProvider (handles deepseek → openai) */
+export function toPiProvider(id: ProviderId): string {
+  return PROVIDER_PRESETS[id].piProviderOverride ?? id;
+}
+
+/**
+ * Get the env var name for a provider's API key, using pi-ai as source of truth.
+ * DeepSeek is not in pi-ai, so we hardcode its env var.
+ */
+const EXTRA_ENV_KEYS: Partial<Record<ProviderId, string>> = {
+  deepseek: 'DEEPSEEK_API_KEY',
+};
+
+export function getApiKeyEnvVar(id: ProviderId): string | undefined {
+  if (EXTRA_ENV_KEYS[id]) return EXTRA_ENV_KEYS[id];
+  return piEnvVarName(toPiProvider(id));
+}
+
+/** Read the actual API key from env for a provider */
+export function getApiKeyFromEnv(id: ProviderId): string | undefined {
+  if (id === 'deepseek') return process.env.DEEPSEEK_API_KEY;
+  return piGetEnvApiKey(toPiProvider(id) as KnownProvider);
+}
+
+/**
+ * Get the default baseUrl for a provider from pi-ai's model registry.
+ * For deepseek, returns its fixed baseUrl.
+ */
+export function getDefaultBaseUrl(id: ProviderId): string {
+  const preset = PROVIDER_PRESETS[id];
+  if (preset.fixedBaseUrl) return preset.fixedBaseUrl;
+  try {
+    const models = piGetModels(toPiProvider(id) as any);
+    return models[0]?.baseUrl ?? '';
+  } catch {
+    return '';
+  }
+}
+
+/**
+ * Get the default API type for a provider from pi-ai's model registry.
+ * Used as fallback when constructing models not in the registry.
+ */
+export function getDefaultApi(id: ProviderId): string {
+  try {
+    const models = piGetModels(toPiProvider(id) as any);
+    return models[0]?.api ?? 'openai-completions';
+  } catch {
+    return 'openai-completions';
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Internal: reverse-engineer pi-ai's env var name mapping (for UI display)
+// ---------------------------------------------------------------------------
+const PI_ENV_MAP: Record<string, string> = {
+  anthropic: 'ANTHROPIC_API_KEY',
+  openai: 'OPENAI_API_KEY',
+  'azure-openai-responses': 'AZURE_OPENAI_API_KEY',
+  google: 'GEMINI_API_KEY',
+  groq: 'GROQ_API_KEY',
+  cerebras: 'CEREBRAS_API_KEY',
+  xai: 'XAI_API_KEY',
+  openrouter: 'OPENROUTER_API_KEY',
+  zai: 'ZAI_API_KEY',
+  mistral: 'MISTRAL_API_KEY',
+  minimax: 'MINIMAX_API_KEY',
+  huggingface: 'HF_TOKEN',
+  'kimi-coding': 'KIMI_API_KEY',
+};
+
+function piEnvVarName(piProvider: string): string | undefined {
+  return PI_ENV_MAP[piProvider];
+}

package/app/lib/agent/tools.ts

@@ -4,7 +4,7 @@ import type { AgentTool, AgentToolResult } from '@mariozechner/pi-agent-core';
 import {
   searchFiles, getFileContent, getFileTree, getRecentlyModified,
   saveFileContent, createFile, appendToFile, insertAfterHeading, updateSection,
-  deleteFile, renameFile, moveFile, findBacklinks, gitLog, gitShowFile, appendCsvRow,
+  moveToTrashFile, renameFile, moveFile, findBacklinks, gitLog, gitShowFile, appendCsvRow,
   getMindRoot,
 } from '@/lib/fs';
 import { readSkillContentByName, scanSkillDirs } from '@/lib/pi-integration/skills';
@@ -239,6 +239,28 @@ export function getOrganizeTools(): AgentTool<any>[] {
   return knowledgeBaseTools.filter(t => ORGANIZE_TOOL_NAMES.has(t.name));
 }
 
+/**
+ * Read-only tool set for Chat mode.
+ *
+ * Allows searching and reading the knowledge base + web access,
+ * but blocks all write operations. Extensible: add tool names here
+ * to grant more read-only capabilities to Chat mode.
+ */
+const CHAT_TOOL_NAMES = new Set([
+  'list_files',
+  'read_file',
+  'read_file_chunk',
+  'search',
+  'get_recent',
+  'get_backlinks',
+  'web_search',
+  'web_fetch',
+]);
+
+export function getChatTools(): AgentTool<any>[] {
+  return knowledgeBaseTools.filter(t => CHAT_TOOL_NAMES.has(t.name));
+}
+
 export async function getRequestScopedTools(): Promise<AgentTool<any>[]> {
   const baseTools = [...knowledgeBaseTools, ...a2aTools, ...acpTools];
   try {
@@ -685,11 +707,11 @@ export const knowledgeBaseTools: AgentTool<any>[] = [
   {
     name: 'delete_file',
     label: 'Delete File',
-    description: 'Permanently delete a file from the knowledge base. This is destructive and cannot be undone.',
+    description: 'Delete a file from the knowledge base. The file is moved to trash and can be recovered within 30 days.',
     parameters: PathParam,
     execute: safeExecute(async (_id, params: Static<typeof PathParam>) => {
-      deleteFile(params.path);
-      return textResult(`File deleted: ${params.path}`);
+      const meta = moveToTrashFile(params.path);
+      return textResult(`Moved to trash: ${params.path} (recoverable for 30 days, trashId: ${meta.id})`);
     }),
   },
 

package/app/lib/api.ts

@@ -36,7 +36,9 @@ export async function apiFetch<T>(url: string, opts: ApiFetchOptions = {}): Prom
   }
 
   if (timeout > 0 && controller) {
-    timeoutId = setTimeout(() => controller.abort(), timeout);
+    timeoutId = setTimeout(() => {
+      controller.abort(new Error(`Request timed out after ${Math.round(timeout / 1000)}s`));
+    }, timeout);
   }
 
   // Bridge caller-provided AbortSignal so both timeout and external cancel work.

package/app/lib/core/agent-audit-log.ts

@@ -9,6 +9,8 @@ export interface AgentAuditEvent {
   result: 'ok' | 'error';
   message?: string;
   durationMs?: number;
+  /** Name of the agent that performed this operation (e.g. "claude-code", "cursor"). */
+  agentName?: string;
   op?: 'append' | 'legacy_agent_audit_md_import' | 'legacy_agent_log_jsonl_import';
 }
 
@@ -19,6 +21,8 @@ export interface AgentAuditInput {
   result: 'ok' | 'error';
   message?: string;
   durationMs?: number;
+  /** Name of the agent that performed this operation. */
+  agentName?: string;
 }
 
 interface AgentAuditState {
@@ -111,6 +115,7 @@ interface LegacyAgentOp {
   result?: 'ok' | 'error';
   message?: string;
   durationMs?: number;
+  agentName?: string;
 }
 
 function parseLegacyMdBlocks(raw: string): LegacyAgentOp[] {
@@ -253,6 +258,7 @@ export function appendAgentAuditEvent(mindRoot: string, input: AgentAuditInput):
     result: input.result === 'error' ? 'error' : 'ok',
     message: normalizeMessage(input.message),
     durationMs: typeof input.durationMs === 'number' ? input.durationMs : undefined,
+    agentName: typeof input.agentName === 'string' && input.agentName.trim() ? input.agentName.trim() : undefined,
     op: 'append',
   };
   state.events.unshift(event);
@@ -275,6 +281,7 @@ export function parseAgentAuditJsonLines(raw: string): AgentAuditInput[] {
     result: entry.result === 'error' ? 'error' : 'ok',
     message: normalizeMessage(entry.message),
     durationMs: typeof entry.durationMs === 'number' ? entry.durationMs : undefined,
+    agentName: typeof entry.agentName === 'string' ? entry.agentName : undefined,
   }));
 }
 

package/app/lib/core/fs-ops.ts

@@ -38,11 +38,16 @@ export function writeFile(mindRoot: string, filePath: string, content: string):
  */
 export function createFile(mindRoot: string, filePath: string, initialContent = ''): void {
   const resolved = resolveSafe(mindRoot, filePath);
-  if (fs.existsSync(resolved)) {
-    throw new MindOSError(ErrorCodes.FILE_ALREADY_EXISTS, `File already exists: ${filePath}`, { filePath });
-  }
   fs.mkdirSync(path.dirname(resolved), { recursive: true });
-  fs.writeFileSync(resolved, initialContent, 'utf-8');
+  try {
+    // 'wx' flag: create exclusively — fails atomically if file already exists (no TOCTOU race)
+    fs.writeFileSync(resolved, initialContent, { encoding: 'utf-8', flag: 'wx' });
+  } catch (err: unknown) {
+    if (err instanceof Error && 'code' in err && (err as NodeJS.ErrnoException).code === 'EEXIST') {
+      throw new MindOSError(ErrorCodes.FILE_ALREADY_EXISTS, `File already exists: ${filePath}`, { filePath });
+    }
+    throw err;
+  }
 }
 
 /**