mixdog 0.9.151 → 0.9.152

package/src/session-runtime/goal-runtime.test.mjs

@@ -0,0 +1,108 @@
+import assert from 'node:assert/strict';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import test from 'node:test';
+
+import {
+  createGoalRuntime,
+  DEFAULT_GOAL_TIME_LIMIT_MS,
+  parseGoalDuration,
+} from './goal-runtime.mjs';
+
+test('Goal runtime persists criteria, enforces completion evidence, and archives after user input', async () => {
+  const dataDir = mkdtempSync(join(tmpdir(), 'mixdog-goal-'));
+  let clock = 1_800_000_000_000;
+  const runtime = createGoalRuntime({ dataDir, now: () => clock });
+  try {
+    const created = await runtime.control('sess_goal_main', {
+      command: 'Ship Goal mode --time 2h',
+    });
+    assert.equal(created.goal.status, 'active');
+    assert.equal(created.goal.timeLimitMs, 2 * 60 * 60 * 1000);
+    assert.equal(created.goal.criteriaTotal, 0);
+
+    const criteria = [
+      { text: 'State is durable', satisfied: true, evidence: 'persistence test passed' },
+      { text: 'Idle continuation works', satisfied: false, evidence: '' },
+    ];
+    await runtime.executeTool('update_goal', {
+      success_criteria: criteria,
+      progress_summary: 'State complete; continuation remains.',
+    }, { callerSessionId: 'sess_goal_main' });
+
+    await assert.rejects(
+      runtime.executeTool('update_goal', {
+        status: 'complete',
+        completion_evidence: 'partial evidence',
+      }, { callerSessionId: 'sess_goal_main' }),
+      /success criteria remain unsatisfied/,
+    );
+
+    clock += 12 * 60 * 1000;
+    const completedCriteria = criteria.map((criterion) => ({
+      ...criterion,
+      satisfied: true,
+      evidence: criterion.evidence || 'continuation test passed',
+    }));
+    const completedText = await runtime.executeTool('update_goal', {
+      success_criteria: completedCriteria,
+      status: 'complete',
+      completion_evidence: 'All required checks passed.',
+    }, { callerSessionId: 'sess_goal_main' });
+    const completed = JSON.parse(completedText).goal;
+    assert.equal(completed.status, 'complete');
+    assert.equal(completed.criteriaCompleted, 2);
+    assert.equal(completed.timeUsedMs, 12 * 60 * 1000);
+
+    await runtime.archiveCompletedOnUserInput('sess_goal_main');
+    assert.equal(runtime.snapshot('sess_goal_main'), null);
+    assert.equal(runtime.storedSnapshot('sess_goal_main').status, 'complete');
+
+    const reloaded = createGoalRuntime({ dataDir, now: () => clock });
+    try {
+      assert.equal(reloaded.snapshot('sess_goal_main'), null);
+      assert.equal(reloaded.storedSnapshot('sess_goal_main').completionEvidence, 'All required checks passed.');
+    } finally {
+      reloaded.close();
+    }
+  } finally {
+    runtime.close();
+    rmSync(dataDir, { recursive: true, force: true });
+  }
+});
+
+test('Goal continuation parks only for active agent work and the deadline limits new turns', async () => {
+  const dataDir = mkdtempSync(join(tmpdir(), 'mixdog-goal-limit-'));
+  let clock = 1_900_000_000_000;
+  const runtime = createGoalRuntime({ dataDir, now: () => clock });
+  try {
+    await runtime.control('sess_goal_limit', { action: 'create', objective: 'Finish the objective' });
+    const parked = runtime.continuation('sess_goal_limit', {
+      agentStatus: { agentJobs: [{ status: 'running' }] },
+    });
+    assert.equal(parked.run, false);
+    assert.equal(parked.reason, 'agent-running');
+
+    const shellIgnored = runtime.continuation('sess_goal_limit', {
+      agentStatus: { agentJobs: [], shellJobs: [{ status: 'running' }] },
+    });
+    assert.equal(shellIgnored.run, true);
+    assert.match(shellIgnored.prompt, /Active Goal/);
+
+    clock += DEFAULT_GOAL_TIME_LIMIT_MS + 1;
+    const limited = runtime.snapshot('sess_goal_limit');
+    assert.equal(limited.status, 'budget_limited');
+    assert.equal(runtime.continuation('sess_goal_limit').run, false);
+  } finally {
+    runtime.close();
+    rmSync(dataDir, { recursive: true, force: true });
+  }
+});
+
+test('Goal duration parser accepts compound limits and rejects unsafe values', () => {
+  assert.equal(parseGoalDuration('1h30m'), 90 * 60 * 1000);
+  assert.equal(parseGoalDuration('2d 4h'), (2 * 24 + 4) * 60 * 60 * 1000);
+  assert.throws(() => parseGoalDuration('30s'), /at least 1 minute/);
+  assert.throws(() => parseGoalDuration('8d'), /exceeds 7 days/);
+});

package/src/session-runtime/lifecycle-api.mjs

@@ -18,10 +18,13 @@ import {
 import { SessionClosedError } from '../runtime/agent/orchestrator/session/manager/session-errors.mjs';
 import { saveSession } from '../runtime/agent/orchestrator/session/store.mjs';
 
-function resolveResumeCwd(session, currentCwd) {
+export function resolveResumeCwd(session, currentCwd) {
   const desktop = session?.desktopSession;
   if (desktop?.classification === 'project') {
-    return clean(desktop.projectPath) || session?.cwd || currentCwd;
+    // `session.cwd` is the execution source of truth. Older builds updated it
+    // on `cwd set` without updating desktopSession.projectPath, so preferring
+    // the duplicate UI metadata reverted the Project after a restart.
+    return clean(session?.cwd) || clean(desktop.projectPath) || currentCwd;
   }
   if (desktop?.classification === 'task') {
     // Desktop task sessions deliberately stay in the app-managed unclassified
@@ -80,8 +83,8 @@ export function createLifecycleApi(deps) {
     computeContextStatus, invalidateContextStatusCache, invalidatePreSessionToolSurface,
     applyResolvedCwd, resolveRoute, applyDeferredToolSurface, getStandaloneTools,
     beginRoutePreparation, clearRoutePreparation,
-    notificationListeners, clearRuntimeNotifications,
-    disposeSessionTitles, abortActiveTurns, getReservedSessionId,
+    notificationListeners, clearRuntimeNotifications, goalRuntime,
+    disposeSessionTitles, disposeGlobalExtensionSubscription, abortActiveTurns, getReservedSessionId,
   } = deps;
   const closeSurfaceSession = (session, reason, options) => {
     if (!session?.id) return false;
@@ -198,6 +201,7 @@ export function createLifecycleApi(deps) {
       // of reaping every session's jobs. CLI exit paths never set this.
       const keepBackgroundWork = options?.keepBackgroundWork === true;
       setCloseRequested(true);
+      try { disposeGlobalExtensionSubscription?.(); } catch {}
       const closingTurnId = getSession()?.id || getReservedSessionId?.() || 'pending';
       try {
         abortActiveTurns?.(new SessionClosedError(
@@ -348,6 +352,7 @@ export function createLifecycleApi(deps) {
       invalidateContextStatusCache();
       if (typeof clearRuntimeNotifications === 'function') clearRuntimeNotifications();
       else notificationListeners?.clear?.();
+      try { goalRuntime?.close?.(); } catch {}
       const shellJobsStop = teardownReapsWork && globalThis.__mixdogShellJobsRuntimeLoaded === true
         ? import('../runtime/agent/orchestrator/tools/builtin/shell-jobs.mjs')
           .then((mod) => mod?.shutdownShellJobs?.(reason, {
@@ -616,6 +621,15 @@ export function createLifecycleApi(deps) {
     async inheritFrom(sourceSessionId) {
       const id = clean(sourceSessionId);
       if (!id) throw new TypeError('inheritFrom: source session id is required');
+      // A daemon-created heir is still only RESERVED when the desktop calls
+      // this: reserveSessionId starts the materializing create in the
+      // background. Join that single-flight instead of rejecting a session
+      // that is about to exist. (The TUI path already ran newSession().)
+      if (!getSession()?.id
+        && clean(getReservedSessionId?.())
+        && typeof createCurrentSession === 'function') {
+        await createCurrentSession('inherit');
+      }
       const target = getSession();
       if (!target?.id) throw new Error('inheritFrom: no session is open');
       if (target.id === id) throw new Error('inheritFrom: a session cannot inherit from itself');

package/src/session-runtime/lifecycle-api.test.mjs

@@ -0,0 +1,21 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+
+import { resolveResumeCwd } from './lifecycle-api.mjs';
+
+test('project resume prefers canonical session cwd over stale desktop metadata', () => {
+  assert.equal(resolveResumeCwd({
+    cwd: 'C:\\Project\\mixdog',
+    desktopSession: {
+      classification: 'project',
+      projectPath: 'C:\\Project\\GamerScroll',
+    },
+  }, 'C:\\fallback'), 'C:\\Project\\mixdog');
+});
+
+test('unclassified desktop task resume stays in its host-managed workspace', () => {
+  assert.equal(resolveResumeCwd({
+    cwd: 'C:\\old-transient',
+    desktopSession: { classification: 'task', projectPath: null },
+  }, 'C:\\task-workspace'), 'C:\\task-workspace');
+});

package/src/session-runtime/mcp-glue.mjs

@@ -1,34 +1,10 @@
 // MCP config/status/connect glue. Mutable runtime state is dependency-injected
 // through accessors and the caller-owned `state` object.
+import { homedir } from 'node:os';
 import { resolve } from 'node:path';
-import { statSync } from 'node:fs';
 import { clean } from './session-text.mjs';
-import { normalizeMcpProjectPathKey, readProjectMcpServers } from './plugin-mcp.mjs';
 import { envFlag } from './env.mjs';
 
-// Cache project-local `.mcp.json` reads by path + mtime so repeated mcpStatus()
-// calls skip existsSync+readFileSync+JSON.parse when the file is unchanged.
-// Invalidated automatically on any mtime change (or create/delete via mtime=0).
-const projectMcpCache = new Map();
-const PROJECT_MCP_CACHE_MAX = 32;
-export function invalidateProjectMcpCache(cwd) {
-  projectMcpCache.delete(resolve(cwd || '.', '.mcp.json'));
-}
-function cachedProjectMcpServers(cwd) {
-  const path = resolve(cwd || '.', '.mcp.json');
-  let mtimeMs = 0;
-  try { mtimeMs = statSync(path).mtimeMs; } catch { mtimeMs = 0; }
-  const hit = projectMcpCache.get(path);
-  if (hit && hit.mtimeMs === mtimeMs) return hit.value;
-  const value = readProjectMcpServers(cwd);
-  // Bound the cache: Map preserves insertion order, so drop the oldest entry.
-  if (!projectMcpCache.has(path) && projectMcpCache.size >= PROJECT_MCP_CACHE_MAX) {
-    projectMcpCache.delete(projectMcpCache.keys().next().value);
-  }
-  projectMcpCache.set(path, { mtimeMs, value });
-  return value;
-}
-
 export function createMcpGlue({
   mcpClient,
   getConfig,
@@ -51,29 +27,43 @@ export function createMcpGlue({
   // (precedence: project > user config). `sources[name]` records each server's
   // origin ('config' | 'project') for status reporting.
   function resolveEffectiveMcpServers() {
-    // Benchmark/embedding guard: do not even inspect project `.mcp.json`.
+    // MCP is machine-global. Project `.mcp.json` files and per-project
+    // overrides are intentionally outside the runtime resolution chain.
     if (envFlag('MIXDOG_DISABLE_MCP')) return { servers: {}, sources: {} };
     const config = getConfig();
     const configured = config?.mcpServers && typeof config.mcpServers === 'object'
       ? config.mcpServers
       : {};
-    const projectKey = normalizeMcpProjectPathKey(getCurrentCwd());
-    const overrides = config?.mcpProjectOverrides?.[projectKey];
-    const foldedConfigured = {};
+    const servers = {};
     for (const [name, cfg] of Object.entries(configured)) {
-      const override = overrides?.[name];
-      foldedConfigured[name] = typeof override?.enabled === 'boolean'
-        ? { ...cfg, enabled: override.enabled }
-        : cfg;
+      servers[name] = {
+        ...cfg,
+        ...(cfg?._mixdogPluginDisabled === true ? { enabled: false } : {}),
+      };
     }
-    const project = cachedProjectMcpServers(getCurrentCwd());
-    const servers = { ...foldedConfigured, ...project };
     const sources = {};
     for (const name of Object.keys(configured)) sources[name] = 'config';
-    for (const name of Object.keys(project)) sources[name] = 'project';
     return { servers, sources };
   }
 
+  function getMcpServerConfig(name) {
+    const serverName = clean(name);
+    if (!serverName) throw new Error('MCP server name is required');
+    const { servers } = resolveEffectiveMcpServers();
+    const effective = servers[serverName];
+    if (!effective) throw new Error(`MCP server not configured: ${serverName}`);
+    const raw = getConfig()?.mcpServers?.[serverName];
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+      throw new Error(`MCP server config is unavailable: ${serverName}`);
+    }
+    return {
+      name: serverName,
+      source: 'config',
+      enabled: effective.enabled !== false,
+      config: { ...raw },
+    };
+  }
+
   function mcpStatus() {
     if (envFlag('MIXDOG_DISABLE_MCP')) {
       return { servers: [], configuredCount: 0, connectedCount: 0, failedCount: 0 };
@@ -94,6 +84,7 @@ export function createMcpGlue({
         transport: mcpTransportLabel(cfg),
         toolCount: live?.toolCount || 0,
         tools: live?.tools || [],
+        capabilities: live?.capabilities || { tools: false, prompts: false, resources: false },
         error: fail?.msg || null,
         source: sources[name] || 'config',
       });
@@ -118,10 +109,10 @@ export function createMcpGlue({
     const target = clean(name);
     if (!target) return;
     const { servers } = resolveEffectiveMcpServers();
-    // The toggle is applied to whichever source drives this name: project
-    // `.mcp.json` entries persist their `enabled` flag in that file (project >
-    // config precedence) and config entries in mixdog-config, so acting on the
-    // effective entry here keeps live state in sync with the durable flag.
+    // Definitions stay in their original source. Enabled state is folded from
+    // Mixdog's per-project override for both global and `.mcp.json` entries, so
+    // acting on the effective entry keeps live state aligned without rewriting
+    // a shared project file.
     // Changing this server's state clears any stale failure record for it.
     if (Array.isArray(state.mcpFailures)) {
       state.mcpFailures = state.mcpFailures.filter((row) => row.name !== target);
@@ -228,9 +219,16 @@ export function createMcpGlue({
       }
       return Object.keys(out).length > 0 ? out : null;
     };
+    const coerceStringArray = (value) => Array.isArray(value)
+      ? value.map((entry) => clean(entry)).filter(Boolean)
+      : [];
     const withOptionalHeaders = (config) => {
       const headers = coerceStringRecord(input.headers);
       if (headers) config.headers = headers;
+      const bearerTokenEnvVar = clean(input.bearer_token_env_var || input.bearerTokenEnvVar);
+      if (bearerTokenEnvVar) config.bearer_token_env_var = bearerTokenEnvVar;
+      const envHeaders = coerceStringRecord(input.env_http_headers || input.envHttpHeaders);
+      if (envHeaders) config.env_http_headers = envHeaders;
       return config;
     };
     const url = clean(input.url);
@@ -259,15 +257,18 @@ export function createMcpGlue({
       ? input.args.map((v) => String(v)).filter(Boolean)
       : clean(input.args).split(/\s+/).filter(Boolean);
     const requestedCwd = clean(input.cwd);
-    const cwdForServer = requestedCwd ? resolve(currentCwd, requestedCwd) : currentCwd;
-    const root = resolve(currentCwd);
-    const resolvedCwd = resolve(cwdForServer);
-    if (resolvedCwd !== root && !resolvedCwd.startsWith(`${root}\\`) && !resolvedCwd.startsWith(`${root}/`)) {
-      throw new Error('MCP server cwd must stay under the current project');
-    }
-    const config = { type: 'stdio', command, args, cwd: resolvedCwd };
+    const expandedCwd = requestedCwd.replace(/^~(?=$|[\\/])/, homedir());
+    const resolvedCwd = expandedCwd ? resolve(currentCwd, expandedCwd) : '';
+    const config = {
+      type: 'stdio',
+      command,
+      args,
+      ...(resolvedCwd ? { cwd: resolvedCwd } : {}),
+    };
     const env = coerceStringRecord(input.env);
     if (env) config.env = env;
+    const envVars = coerceStringArray(input.env_vars || input.envVars);
+    if (envVars.length > 0) config.env_vars = envVars;
     return { name, config };
   }
 
@@ -309,6 +310,7 @@ export function createMcpGlue({
     mcpTransportLabel,
     resolveEffectiveMcpServers,
     mcpStatus,
+    getMcpServerConfig,
     connectConfiguredMcp,
     awaitInitialMcpConnect,
     normalizeMcpServerInput,

package/src/session-runtime/plugin-mcp-standard.test.mjs

@@ -0,0 +1,177 @@
+import assert from 'node:assert/strict';
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import test from 'node:test';
+
+import { createMcpGlue } from './mcp-glue.mjs';
+import { createResourceApi } from './resource-api.mjs';
+import {
+  mergeMcpServerConfig,
+  readProjectMcpServerConfig,
+  saveProjectMcpServer,
+} from './plugin-mcp.mjs';
+
+test('project MCP edits preserve document shape and unknown fields', () => {
+  const cwd = mkdtempSync(join(tmpdir(), 'mixdog-mcp-standard-'));
+  try {
+    const path = join(cwd, '.mcp.json');
+    writeFileSync(path, `${JSON.stringify({
+      projectMetadata: { owner: 'test' },
+      mcpServers: {
+        demo: {
+          type: 'stdio',
+          command: 'old-command',
+          args: ['--old'],
+          vendorExtension: { keep: true },
+        },
+        sibling: { url: 'https://example.com/mcp', custom: 7 },
+      },
+    }, null, 2)}\n`);
+
+    saveProjectMcpServer(cwd, {
+      originalName: 'demo',
+      name: 'renamed',
+      config: {
+        type: 'http',
+        url: 'https://example.com/new-mcp',
+        headers: { Authorization: '${MCP_TOKEN}' },
+      },
+    });
+
+    const saved = JSON.parse(readFileSync(path, 'utf8'));
+    assert.deepEqual(saved.projectMetadata, { owner: 'test' });
+    assert.deepEqual(saved.mcpServers.sibling, {
+      url: 'https://example.com/mcp',
+      custom: 7,
+    });
+    assert.equal(saved.mcpServers.demo, undefined);
+    assert.deepEqual(saved.mcpServers.renamed, {
+      vendorExtension: { keep: true },
+      type: 'http',
+      url: 'https://example.com/new-mcp',
+      headers: { Authorization: '${MCP_TOKEN}' },
+    });
+    assert.deepEqual(readProjectMcpServerConfig(cwd, 'renamed')?.config, saved.mcpServers.renamed);
+  } finally {
+    rmSync(cwd, { recursive: true, force: true });
+  }
+});
+
+test('MCP transport edits drop stale transport fields but retain extensions', () => {
+  assert.deepEqual(mergeMcpServerConfig({
+    type: 'http',
+    url: 'https://example.com/mcp',
+    headers: { Authorization: 'secret' },
+    bearer_token_env_var: 'MCP_TOKEN',
+    env_http_headers: { 'X-API-Key': 'MCP_API_KEY' },
+    env_vars: ['STALE_STDIO_VALUE'],
+    startupTimeoutSec: 20,
+  }, {
+    type: 'stdio',
+    command: 'server',
+    args: [],
+  }), {
+    startupTimeoutSec: 20,
+    type: 'stdio',
+    command: 'server',
+    args: [],
+  });
+});
+
+test('plugin-disabled MCP cannot be re-enabled by a stale project override', () => {
+  const cwd = mkdtempSync(join(tmpdir(), 'mixdog-mcp-plugin-off-'));
+  try {
+    const config = {
+      mcpServers: {
+        plugin: {
+          command: 'server',
+          _mixdogPluginDisabled: true,
+        },
+      },
+      mcpProjectOverrides: {
+        [cwd]: {
+          plugin: { enabled: true },
+        },
+      },
+    };
+    const glue = createMcpGlue({
+      mcpClient: {
+        resolveMcpTransportKind: () => 'stdio',
+        getMcpServerStatus: () => [],
+      },
+      getConfig: () => config,
+      getCurrentCwd: () => cwd,
+      state: {
+        mcpFailures: [],
+        mcpConnectGeneration: 0,
+        mcpConnectInFlight: null,
+      },
+    });
+    assert.equal(glue.mcpStatus().servers[0]?.enabled, false);
+  } finally {
+    rmSync(cwd, { recursive: true, force: true });
+  }
+});
+
+test('MCP toggle updates the global server and ignores project config and overrides', async () => {
+  const cwd = mkdtempSync(join(tmpdir(), 'mixdog-mcp-override-'));
+  try {
+    const path = join(cwd, '.mcp.json');
+    writeFileSync(path, `${JSON.stringify({
+      mcpServers: {
+        local: { command: 'server', enabled: false, extension: 'kept' },
+      },
+    }, null, 2)}\n`);
+    const before = readFileSync(path, 'utf8');
+    let config = {
+      mcpServers: {
+        local: { command: 'global-server', enabled: false, extension: 'kept' },
+      },
+      mcpProjectOverrides: {
+        [cwd]: {
+          local: { enabled: false },
+        },
+      },
+    };
+    const api = createResourceApi({
+      getConfig: () => config,
+      getSession: () => null,
+      getCurrentCwd: () => cwd,
+      cfgMod: {},
+      mgr: {},
+      saveConfigAndAdopt: (next) => { config = next; },
+      connectConfiguredMcp: async () => ({ servers: [] }),
+      invalidatePreSessionToolSurface: () => {},
+      recreateCurrentSessionIfReady: async () => {},
+      mcpStatus: () => ({ servers: [{ name: 'local', source: 'config' }] }),
+      getActiveTurnCount: () => 0,
+    });
+    await api.setMcpServerEnabled('local', true);
+    assert.equal(config.mcpServers.local.enabled, true);
+    assert.equal(config.mcpServers.local.extension, 'kept');
+    assert.equal(config.mcpProjectOverrides, undefined);
+
+    const glue = createMcpGlue({
+      mcpClient: {
+        resolveMcpTransportKind: () => 'stdio',
+        getMcpServerStatus: () => [],
+      },
+      getConfig: () => config,
+      getCurrentCwd: () => cwd,
+      state: {
+        mcpFailures: [],
+        mcpConnectGeneration: 0,
+        mcpConnectInFlight: null,
+      },
+    });
+
+    const row = glue.mcpStatus().servers.find((server) => server.name === 'local');
+    assert.equal(row?.source, 'config');
+    assert.equal(row?.enabled, true);
+    assert.equal(glue.getMcpServerConfig('local').config.command, 'global-server');
+    assert.equal(readFileSync(path, 'utf8'), before);
+  } finally {
+    rmSync(cwd, { recursive: true, force: true });
+  }
+});

package/src/session-runtime/plugin-mcp.mjs

@@ -1,5 +1,17 @@
 // Plugin/project MCP server discovery + normalization, and skill-file counting.
-import { existsSync, readFileSync, readdirSync, statSync, writeFileSync } from 'node:fs';
+import {
+  chmodSync,
+  closeSync,
+  existsSync,
+  fsyncSync,
+  openSync,
+  readFileSync,
+  readdirSync,
+  renameSync,
+  statSync,
+  unlinkSync,
+  writeFileSync,
+} from 'node:fs';
 import { isAbsolute, join, relative, resolve } from 'node:path';
 import { clean } from './session-text.mjs';
 import { readJsonSafe } from './fs-utils.mjs';
@@ -52,39 +64,101 @@ export function readProjectMcpServers(cwd) {
   return out;
 }
 
-// Persist an enable/disable flag for a project-local `.mcp.json` server, in
-// place, preserving the file's shape. Accepts both the standard
-// `{ mcpServers: {...} }` wrapper and a bare name->cfg map. Writes pretty JSON
-// (2-space indent + trailing newline) so the file stays valid + diff-friendly.
-// Throws if the file is missing/unparseable or the server isn't defined there.
-export function setProjectMcpServerEnabled(cwd, name, enabled) {
+const MCP_TRANSPORT_FIELDS = new Set([
+  'type',
+  'transport',
+  'command',
+  'args',
+  'env',
+  'cwd',
+  'url',
+  'headers',
+  'bearer_token_env_var',
+  'env_http_headers',
+  'env_vars',
+  'autoDetect',
+]);
+
+export function mergeMcpServerConfig(existing, next) {
+  const merged = isPlainObject(existing) ? { ...existing } : {};
+  for (const field of MCP_TRANSPORT_FIELDS) delete merged[field];
+  return { ...merged, ...next };
+}
+
+function readProjectMcpDocument(cwd, allowMissing = false) {
   const path = join(cwd || '.', '.mcp.json');
-  const key = clean(name);
-  if (!key) throw new Error('MCP server name is required');
+  if (!existsSync(path)) {
+    if (allowMissing) return { path, raw: { mcpServers: {} }, usesWrapper: true };
+    throw new Error(`MCP config file not found: ${path}`);
+  }
   let raw;
   try {
     raw = JSON.parse(readFileSync(path, 'utf8'));
   } catch (error) {
-    throw new Error(`cannot update ${path}: ${error?.message || String(error)}`);
+    throw new Error(`cannot read ${path}: ${error?.message || String(error)}`);
   }
-  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+  if (!isPlainObject(raw)) throw new Error(`unexpected .mcp.json shape at ${path}`);
+  if (Object.prototype.hasOwnProperty.call(raw, 'mcpServers') && !isPlainObject(raw.mcpServers)) {
     throw new Error(`unexpected .mcp.json shape at ${path}`);
   }
-  const usesWrapper = raw.mcpServers && typeof raw.mcpServers === 'object' && !Array.isArray(raw.mcpServers);
+  const usesWrapper = isPlainObject(raw.mcpServers);
+  const map = usesWrapper ? raw.mcpServers : raw;
+  if (!isPlainObject(map)) throw new Error(`unexpected .mcp.json shape at ${path}`);
+  return { path, raw, usesWrapper };
+}
+
+function writeProjectMcpDocument(path, raw) {
+  let mode = 0o644;
+  try { mode = statSync(path).mode; } catch { /* new file */ }
+  const tempPath = `${path}.tmp-${process.pid}-${Date.now()}`;
+  let fd = null;
+  try {
+    fd = openSync(tempPath, 'w', mode);
+    writeFileSync(fd, `${JSON.stringify(raw, null, 2)}\n`, 'utf8');
+    fsyncSync(fd);
+    closeSync(fd);
+    fd = null;
+    chmodSync(tempPath, mode);
+    renameSync(tempPath, path);
+  } catch (error) {
+    if (fd !== null) {
+      try { closeSync(fd); } catch { /* best effort */ }
+    }
+    try { unlinkSync(tempPath); } catch { /* best effort */ }
+    throw error;
+  }
+}
+
+export function readProjectMcpServerConfig(cwd, name) {
+  const { raw, usesWrapper } = readProjectMcpDocument(cwd);
   const map = usesWrapper ? raw.mcpServers : raw;
+  const key = String(name || '').trim();
   const entryKey = Object.prototype.hasOwnProperty.call(map, key)
     ? key
-    : Object.keys(map).reverse().find((candidate) => clean(candidate) === key);
-  if (!map || typeof map !== 'object' || Array.isArray(map) || !entryKey) {
-    throw new Error(`MCP server not defined in ${path}: ${key}`);
-  }
-  const entry = map[entryKey];
-  if (!entry || typeof entry !== 'object' || Array.isArray(entry)) {
-    throw new Error(`MCP server is not an object in ${path}: ${key}`);
+    : Object.keys(map).find((candidate) => String(candidate || '').trim() === key);
+  return entryKey && isPlainObject(map[entryKey]) ? { name: entryKey, config: { ...map[entryKey] } } : null;
+}
+
+export function saveProjectMcpServer(cwd, { originalName = '', name, config }) {
+  const { path, raw, usesWrapper } = readProjectMcpDocument(cwd, !originalName);
+  const map = usesWrapper ? raw.mcpServers : raw;
+  const target = String(name || '').trim();
+  const original = String(originalName || '').trim();
+  if (!target) throw new Error('MCP server name is required');
+  const entryKey = original
+    ? (Object.prototype.hasOwnProperty.call(map, original)
+      ? original
+      : Object.keys(map).find((candidate) => String(candidate || '').trim() === original))
+    : null;
+  if (original && !entryKey) throw new Error(`MCP server not defined in ${path}: ${original}`);
+  if (target !== entryKey && Object.prototype.hasOwnProperty.call(map, target)) {
+    throw new Error(`MCP server already exists in ${path}: ${target}`);
   }
-  map[entryKey] = { ...entry, enabled: enabled !== false };
-  writeFileSync(path, `${JSON.stringify(raw, null, 2)}\n`, 'utf8');
-  return raw;
+  const existing = entryKey ? map[entryKey] : {};
+  if (entryKey && entryKey !== target) delete map[entryKey];
+  map[target] = mergeMcpServerConfig(existing, config);
+  writeProjectMcpDocument(path, raw);
+  return { name: target, source: 'project', path, config: { ...map[target] } };
 }
 
 function isPlainObject(value) {