QwenLM
diff --git a/‎docs/users/configuration/settings.md‎
Lines changed: 4 additions & 1 deletion b/‎docs/users/configuration/settings.md‎
Lines changed: 4 additions & 1 deletion
diff --git a/‎docs/users/features/mcp.md‎
Lines changed: 56 additions & 0 deletions b/‎docs/users/features/mcp.md‎
Lines changed: 56 additions & 0 deletions
diff --git a/‎packages/cli/src/acp-integration/acpAgent.test.ts‎
Lines changed: 94 additions & 0 deletions b/‎packages/cli/src/acp-integration/acpAgent.test.ts‎
Lines changed: 94 additions & 0 deletions
diff --git a/‎packages/cli/src/acp-integration/acpAgent.ts‎
Lines changed: 41 additions & 0 deletions b/‎packages/cli/src/acp-integration/acpAgent.ts‎
Lines changed: 41 additions & 0 deletions
@@ -589,7 +589,10 @@ For authentication-related variables (like `OPENAI_*`) and the recommended `.qwe
 | `CODE_ASSIST_ENDPOINT`                             | Specifies the endpoint for the code assist server.                                                                                                                                                                                                                                | This is useful for development and testing.                                                                                                                                                                                                                                                                                                                                                                                                                                        |
 | `QWEN_CODE_MAX_OUTPUT_TOKENS`                      | Overrides the default maximum output tokens per response. When not set, Qwen Code uses an adaptive strategy: starts with 8K tokens and automatically retries with 64K if the response is truncated. Set this to a specific value (e.g., `16000`) to use a fixed limit instead.    | Takes precedence over the capped default (8K) but is overridden by `samplingParams.max_tokens` in settings. Disables automatic escalation when set. Example: `export QWEN_CODE_MAX_OUTPUT_TOKENS=16000`                                                                                                                                                                                                                                                                            |
 | `QWEN_CODE_UNATTENDED_RETRY`                       | Set to `true` or `1` to enable persistent retry mode. When enabled, transient API capacity errors (HTTP 429 Rate Limit and 529 Overloaded) are retried indefinitely with exponential backoff (capped at 5 minutes per retry) and heartbeat keepalives every 30 seconds on stderr. | Designed for CI/CD pipelines and background automation where long-running tasks should survive temporary API outages. Must be set explicitly — `CI=true` alone does **not** activate this mode. See [Headless Mode](../features/headless#persistent-retry-mode) for details. Example: `export QWEN_CODE_UNATTENDED_RETRY=1`                                                                                                                                                        |
-| `QWEN_CODE_PROFILE_STARTUP`                        | Set to `1` to enable startup performance profiling. Writes a JSON timing report to `~/.qwen/startup-perf/` with per-phase durations.                                                                                                                                              | Only active inside the sandbox child process. Zero overhead when not set. Example: `export QWEN_CODE_PROFILE_STARTUP=1`                                                                                                                                                                                                                                                                                                                                                            |
+| `QWEN_CODE_PROFILE_STARTUP`                        | Set to `1` to enable startup performance profiling. Writes a JSON timing report to `~/.qwen/startup-perf/` with per-phase durations.                                                                                                                                              | Only active inside the sandbox child process (or with `QWEN_CODE_PROFILE_STARTUP_OUTER=1`). Zero overhead when not set. Example: `export QWEN_CODE_PROFILE_STARTUP=1`                                                                                                                                                                                                                                                                                                              |
+| `QWEN_CODE_PROFILE_STARTUP_OUTER`                  | Set to `1` together with `QWEN_CODE_PROFILE_STARTUP=1` to also collect a startup profile in the outer (pre-sandbox) process. Outer-process reports get an `outer-` filename prefix to keep them distinct from the sandbox child's report.                                         | Off by default — only the sandbox child collects, to avoid duplicate reports. Useful for local development where the cli isn't relaunched into a sandbox.                                                                                                                                                                                                                                                                                                                          |
+| `QWEN_CODE_PROFILE_STARTUP_NO_HEAP`                | Set to `1` together with `QWEN_CODE_PROFILE_STARTUP=1` to skip the per-checkpoint `process.memoryUsage()` snapshots. Useful when measuring the profiler's own Heisenberg overhead.                                                                                                | Off by default. Heap snapshots cost ~50 µs each (well below 1% of total startup) so most users should leave this alone.                                                                                                                                                                                                                                                                                                                                                            |
+| `QWEN_CODE_LEGACY_MCP_BLOCKING`                    | Set to `1` to restore the pre-progressive-MCP behavior where `Config.initialize()` waits synchronously for every configured MCP server's discover handshake before returning.                                                                                                     | Off by default. Modern qwen-code lets MCP servers come online in the background while the UI is already interactive; the model sees each batch of new tools within ~16 ms of the server settling. This flag is kept as a rollback escape hatch for ≥ 1 release. Example: `export QWEN_CODE_LEGACY_MCP_BLOCKING=1`                                                                                                                                                                  |
 
 When both user-level `.env` files define the same variable, the Qwen-specific
 file wins: `<QWEN_HOME>/.env` (or `~/.qwen/.env` when `QWEN_HOME` is unset) is
 
@@ -147,6 +147,62 @@ CLI:
 qwen mcp add --transport sse sseServer http://localhost:8080/sse --timeout 30000
 ```
 
+## Progressive availability and discovery timeouts
+
+Qwen Code discovers MCP servers in the background after the UI is already
+interactive. You see the cli's first prompt within a few hundred
+milliseconds even when one of your MCP servers takes several seconds
+(or never responds), and the model's tool list updates within roughly
+one frame (~16 ms) of each server completing its discover handshake.
+
+- **Interactive mode**: the UI appears immediately; an MCP status pill in
+  the bottom-right shows `N/M MCP servers ready` while discovery is in
+  flight. Sending a prompt before MCP finishes simply means the model
+  sees the tools that are ready _at that moment_; subsequent prompts see
+  more tools as servers come online.
+- **Non-interactive mode** (`--prompt`, stream-json, ACP): the cli still
+  waits for MCP discovery to settle before sending the first prompt, so
+  scripted / piped invocations see the same complete tool set the
+  legacy synchronous behavior produced.
+
+### Per-server `discoveryTimeoutMs`
+
+Each MCP server gets a discovery-only timeout that caps how long the
+initial handshake (`connect` + `tools/list` + `prompts/list` +
+`resources/list`) is allowed to take. Defaults:
+
+- **stdio servers**: 30 s
+- **remote HTTP / SSE servers**: 5 s (network risk is higher)
+
+Override per server when needed:
+
+```jsonc
+{
+  "mcpServers": {
+    "slow-stdio": {
+      "command": "node",
+      "args": ["./slow-server.js"],
+      "discoveryTimeoutMs": 60000,
+    },
+    "flaky-remote": {
+      "httpUrl": "https://example.com/mcp",
+      "discoveryTimeoutMs": 10000,
+    },
+  },
+}
+```
+
+The existing `timeout` field is **tool-call** timeout (used for each
+`tools/call` request, default 10 minutes) and is unaffected by
+`discoveryTimeoutMs` — a long-running tool invocation is not a startup
+pathology.
+
+### Rolling back progressive MCP
+
+If you need the old synchronous behavior (cli waits for every MCP server
+before showing any UI), set `QWEN_CODE_LEGACY_MCP_BLOCKING=1` in your
+environment. This is kept as an escape hatch for at least one release.
+
 ## Safety and control
 
 ### Trust (skip confirmations)
 
@@ -166,6 +166,7 @@ describe('runAcpAgent shutdown cleanup', () => {
     // Reset mockConfig after clearAllMocks
     mockConfig = {
       initialize: vi.fn().mockResolvedValue(undefined),
+      waitForMcpReady: vi.fn().mockResolvedValue(undefined),
       getHookSystem: vi.fn().mockReturnValue(undefined),
       getDisableAllHooks: vi.fn().mockReturnValue(false),
       hasHooksForEvent: vi.fn().mockReturnValue(false),
@@ -343,6 +344,7 @@ describe('runAcpAgent SessionEnd hooks', () => {
     };
     mockConfig = {
       initialize: vi.fn().mockResolvedValue(undefined),
+      waitForMcpReady: vi.fn().mockResolvedValue(undefined),
       getHookSystem: vi.fn().mockReturnValue(mockHookSystem),
       getDisableAllHooks: vi.fn().mockReturnValue(false),
       hasHooksForEvent: vi.fn().mockReturnValue(true),
@@ -684,6 +686,7 @@ describe('QwenAgent MCP SSE/HTTP support', () => {
 
     mockConfig = {
       initialize: vi.fn().mockResolvedValue(undefined),
+      waitForMcpReady: vi.fn().mockResolvedValue(undefined),
       getHookSystem: vi.fn().mockReturnValue(undefined),
       getDisableAllHooks: vi.fn().mockReturnValue(false),
       hasHooksForEvent: vi.fn().mockReturnValue(false),
@@ -744,6 +747,7 @@ describe('QwenAgent MCP SSE/HTTP support', () => {
   function makeInnerConfig() {
     return {
       initialize: vi.fn().mockResolvedValue(undefined),
+      waitForMcpReady: vi.fn().mockResolvedValue(undefined),
       getModelsConfig: vi.fn().mockReturnValue({
         getCurrentAuthType: vi.fn().mockReturnValue('api-key'),
       }),
@@ -759,6 +763,7 @@ describe('QwenAgent MCP SSE/HTTP support', () => {
       getGeminiClient: vi.fn().mockReturnValue({
         isInitialized: vi.fn().mockReturnValue(true),
         initialize: vi.fn().mockResolvedValue(undefined),
+        waitForMcpReady: vi.fn().mockResolvedValue(undefined),
       }),
       getFileSystemService: vi.fn().mockReturnValue(undefined),
       setFileSystemService: vi.fn(),
@@ -1122,6 +1127,92 @@ describe('QwenAgent MCP SSE/HTTP support', () => {
     await agentPromise;
   });
 
+  it('per-session newSession surfaces MCP failures to stderr (round-7 fix: was silent before)', async () => {
+    // Round-7 regression: `QwenAgent.initializeConfig()` (per-session ACP
+    // path) calls `waitForMcpReady()` but the round-4 fix only added the
+    // failure warning to the top-level `runAcpAgent` path. Per-session
+    // configs with failed MCP servers silently fell back to built-in
+    // tools with zero user-visible indication, despite the inline comment
+    // claiming "Same reasoning as the top-level runAcpAgent path."
+    const innerConfig = await setupSessionMocks('session-failed-mcp');
+    (
+      innerConfig as unknown as { getFailedMcpServerNames: () => string[] }
+    ).getFailedMcpServerNames = vi
+      .fn()
+      .mockReturnValue(['broken-server-a', 'broken-server-b']);
+    const stderrWrite = vi
+      .spyOn(process.stderr, 'write')
+      .mockImplementation(() => true);
+
+    const agentPromise = runAcpAgent(
+      mockConfig,
+      makeSessionSettings(),
+      mockArgv,
+    );
+    await vi.waitFor(() => expect(capturedAgentFactory).toBeDefined());
+
+    const agent = capturedAgentFactory!({
+      get closed() {
+        return mockConnectionState.promise;
+      },
+    }) as AgentLike;
+
+    await agent.newSession({ cwd: '/tmp', mcpServers: [] });
+
+    // The warning must list both failed servers and mention "Warning:"
+    // exactly like the top-level path and the other non-interactive
+    // entry points (`gemini.tsx`, `session.ts`).
+    const matchingWrite = stderrWrite.mock.calls.find(
+      ([msg]) =>
+        typeof msg === 'string' &&
+        msg.includes('Warning: MCP server(s) failed to start') &&
+        msg.includes('broken-server-a') &&
+        msg.includes('broken-server-b'),
+    );
+    expect(matchingWrite).toBeDefined();
+
+    stderrWrite.mockRestore();
+    mockConnectionState.resolve();
+    await agentPromise;
+  });
+
+  it('per-session newSession is safe when Config lacks getFailedMcpServerNames (defensive typeof check)', async () => {
+    // Tests pass stubbed Configs without `getFailedMcpServerNames` — the
+    // round-7 fix uses `typeof config.getFailedMcpServerNames ===
+    // 'function'` so it must not throw, and must not write to stderr.
+    await setupSessionMocks('session-stubbed-config');
+    const stderrWrite = vi
+      .spyOn(process.stderr, 'write')
+      .mockImplementation(() => true);
+
+    const agentPromise = runAcpAgent(
+      mockConfig,
+      makeSessionSettings(),
+      mockArgv,
+    );
+    await vi.waitFor(() => expect(capturedAgentFactory).toBeDefined());
+
+    const agent = capturedAgentFactory!({
+      get closed() {
+        return mockConnectionState.promise;
+      },
+    }) as AgentLike;
+
+    await expect(
+      agent.newSession({ cwd: '/tmp', mcpServers: [] }),
+    ).resolves.not.toThrow();
+    const surfacedWarning = stderrWrite.mock.calls.find(
+      ([msg]) =>
+        typeof msg === 'string' &&
+        msg.includes('Warning: MCP server(s) failed to start'),
+    );
+    expect(surfacedWarning).toBeUndefined();
+
+    stderrWrite.mockRestore();
+    mockConnectionState.resolve();
+    await agentPromise;
+  });
+
   it('newSession with SSE MCP server and empty headers passes undefined for headers', async () => {
     await setupSessionMocks('session-sse-noheaders');
 
@@ -1206,6 +1297,7 @@ describe('QwenAgent extMethod renameSession routing', () => {
 
     mockConfig = {
       initialize: vi.fn().mockResolvedValue(undefined),
+      waitForMcpReady: vi.fn().mockResolvedValue(undefined),
       getHookSystem: vi.fn().mockReturnValue(undefined),
       getDisableAllHooks: vi.fn().mockReturnValue(false),
       hasHooksForEvent: vi.fn().mockReturnValue(false),
@@ -1229,6 +1321,7 @@ describe('QwenAgent extMethod renameSession routing', () => {
   ) {
     return {
       initialize: vi.fn().mockResolvedValue(undefined),
+      waitForMcpReady: vi.fn().mockResolvedValue(undefined),
       getModelsConfig: vi.fn().mockReturnValue({
         getCurrentAuthType: vi.fn().mockReturnValue('api-key'),
       }),
@@ -1244,6 +1337,7 @@ describe('QwenAgent extMethod renameSession routing', () => {
       getGeminiClient: vi.fn().mockReturnValue({
         isInitialized: vi.fn().mockReturnValue(true),
         initialize: vi.fn().mockResolvedValue(undefined),
+        waitForMcpReady: vi.fn().mockResolvedValue(undefined),
       }),
       getFileSystemService: vi.fn().mockReturnValue(undefined),
       setFileSystemService: vi.fn(),
 
@@ -84,6 +84,27 @@ export async function runAcpAgent(
   // Initialize config to set up hookSystem (required for SessionStart/SessionEnd hooks)
   // This is needed because gemini.tsx calls runAcpAgent without calling config.initialize()
   await config.initialize();
+  // ACP forwards session messages straight to the model; under progressive
+  // MCP availability `initialize()` returns before MCP servers settle, so
+  // we wait here to keep the first session's tool surface consistent with
+  // the legacy synchronous behavior.
+  await config.waitForMcpReady();
+  // Surface MCP failures to stderr. ACP's stdout is the protocol channel
+  // so info/log writes are already redirected to stderr below, but we
+  // emit this BEFORE that redirection takes effect to keep the message
+  // visible regardless of how the host process is wired.
+  // Defensive against tests that pass a stubbed Config without
+  // `getFailedMcpServerNames`.
+  const failedMcpServers =
+    typeof config.getFailedMcpServerNames === 'function'
+      ? config.getFailedMcpServerNames()
+      : [];
+  if (failedMcpServers.length > 0) {
+    process.stderr.write(
+      `Warning: MCP server(s) failed to start: ${failedMcpServers.join(', ')}. ` +
+        `Continuing with built-in tools and any servers that did connect.\n`,
+    );
+  }
 
   const stdout = Writable.toWeb(process.stdout) as WritableStream;
   const stdin = Readable.toWeb(process.stdin) as ReadableStream<Uint8Array>;
@@ -673,6 +694,26 @@ class QwenAgent implements Agent {
       },
     );
     await config.initialize();
+    // Same reasoning as the top-level runAcpAgent path: ACP feeds session
+    // messages to the model immediately, so we cannot return a Config whose
+    // MCP discovery is still in flight.
+    await config.waitForMcpReady();
+    // Surface MCP failures to stderr — mirrors `runAcpAgent` (lines 95-107)
+    // and the other non-interactive entry points (`gemini.tsx`,
+    // `session.ts`). Without this, per-session ACP configs that lose MCP
+    // servers fall back to built-in-tools-only with no user-visible
+    // indication. Defensive against tests that pass a stubbed Config
+    // without `getFailedMcpServerNames`.
+    const failedMcpServers =
+      typeof config.getFailedMcpServerNames === 'function'
+        ? config.getFailedMcpServerNames()
+        : [];
+    if (failedMcpServers.length > 0) {
+      process.stderr.write(
+        `Warning: MCP server(s) failed to start: ${failedMcpServers.join(', ')}. ` +
+          `Continuing with built-in tools and any servers that did connect.\n`,
+      );
+    }
     return config;
   }