diff --git a/docs/design/npm-background-auto-update.md b/docs/design/npm-background-auto-update.md
new file mode 100644
index 00000000000..c3236c2ef2a
--- /dev/null
+++ b/docs/design/npm-background-auto-update.md
@@ -0,0 +1,60 @@
+# Background npm updates
+
+## Problem
+
+The published CLI is code-split into content-hashed JavaScript chunks. Running
+`npm install -g` from an active session replaces those chunks in place, so a
+later dynamic import in the old process can fail with `ERR_MODULE_NOT_FOUND`.
+Deferring the install until session exit avoids corruption, but turns a
+background update into an exit-time delay and gives users no benefit until they
+leave the session.
+
+## Design
+
+For writable global npm installations, the post-render update check installs
+the exact resolved version under a directory derived from the global launcher:
+
+```text
+~/.qwen/updates/npm/<launcher-id>/versions/<version>/
+```
+
+The version check runs npm in its global context and the staged install uses an
+isolated prefix. The staged command explicitly preserves the original global
+npm configuration, so changing the prefix does not switch registry or
+authentication settings between discovery and installation.
+
+The launcher resolves `QWEN_HOME` from the same home-scoped `.env` files before
+selecting a version. This keeps the bootstrap path aligned with CLI storage even
+though the full environment loader runs later.
+
+The install and activation run in a detached worker, so quitting the TUI does
+not interrupt an update already in progress. After npm exits successfully, the
+worker verifies the package name, version, bundle, and launcher, then atomically
+writes an `active.json` pointer beside that launcher's versions. The global npm
+package is not modified. The already-running process and any child commands it
+starts remain pinned to their original build. On the next invocation, the
+stable launcher reads the pointer and starts the verified version directory.
+
+Each global npm launcher has its own pointer and version payloads, so
+installations under different npm or nvm prefixes can share `~/.qwen` without
+overriding one another or sharing dependencies. A slower concurrent update
+cannot replace a newer active version.
+
+An incomplete install never changes the active pointer. Before activation, the
+worker validates the installed manifest and runs a launcher smoke test. A
+missing, malformed, or launcher-mismatched pointer is ignored and the original
+npm package remains the fallback. The pointer also records the base package and
+launcher identity, so a later explicit global npm install supersedes the
+managed version. Because the launcher is not replaced by managed updates,
+existing `active.json` fields are a compatibility contract: future changes may
+add fields but must not remove or reinterpret them.
+
+Version directories are retained because an older live session may still load
+from them. Cleanup is intentionally deferred until disk usage shows that a
+lease-based collector is necessary.
+
+## Scope
+
+This changes automatic updates for npm installations only. Other package
+managers and standalone archives keep the existing exit-safe behavior until
+they have an equivalent immutable-version installation layout.
diff --git a/packages/cli/src/cli.test.ts b/packages/cli/src/cli.test.ts
index d1b6dac2ff3..af20ba5db5d 100644
--- a/packages/cli/src/cli.test.ts
+++ b/packages/cli/src/cli.test.ts
@@ -12,10 +12,15 @@ import {
   mkdirSync,
   mkdtempSync,
   readFileSync,
+  realpathSync,
+  renameSync,
   rmSync,
+  statSync,
+  utimesSync,
   writeFileSync,
 } from 'node:fs';
 import { execFileSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
 import { tmpdir } from 'node:os';
 import path from 'node:path';
 import { FatalError } from '@qwen-code/qwen-code-core';
@@ -42,6 +47,7 @@ const mocks = vi.hoisted(() => ({
   mcpListHandler: vi.fn(),
   mcpAddHandler: vi.fn(),
   getCliVersion: vi.fn(),
+  installManagedNpmUpdate: vi.fn(),
 }));
 
 vi.mock('./gemini.js', () => ({
@@ -69,6 +75,10 @@ vi.mock('./utils/version.js', () => ({
   getCliVersion: mocks.getCliVersion,
 }));
 
+vi.mock('./utils/managed-npm-update.js', () => ({
+  installManagedNpmUpdate: mocks.installManagedNpmUpdate,
+}));
+
 vi.mock('./commands/mcp.js', () => ({
   mcpCommand: {
     command: 'mcp',
@@ -133,6 +143,8 @@ describe('resolveBootstrapRoute', () => {
 describe('runCliEntry', () => {
   const savedEnv = {
     CLI_VERSION: process.env['CLI_VERSION'],
+    QWEN_CODE_MANAGED_NPM_UPDATE_VERSION:
+      process.env['QWEN_CODE_MANAGED_NPM_UPDATE_VERSION'],
   };
 
   let stdout: string[];
@@ -165,6 +177,12 @@ describe('runCliEntry', () => {
     } else {
       process.env['CLI_VERSION'] = savedEnv.CLI_VERSION;
     }
+    if (savedEnv.QWEN_CODE_MANAGED_NPM_UPDATE_VERSION === undefined) {
+      delete process.env['QWEN_CODE_MANAGED_NPM_UPDATE_VERSION'];
+    } else {
+      process.env['QWEN_CODE_MANAGED_NPM_UPDATE_VERSION'] =
+        savedEnv.QWEN_CODE_MANAGED_NPM_UPDATE_VERSION;
+    }
     vi.restoreAllMocks();
   });
 
@@ -178,6 +196,16 @@ describe('runCliEntry', () => {
     expect(mocks.initCpuProfiler).not.toHaveBeenCalled();
   });
 
+  it('runs a managed update worker without starting the CLI', async () => {
+    process.env['QWEN_CODE_MANAGED_NPM_UPDATE_VERSION'] = '2.0.0';
+
+    await runCliEntry([]);
+
+    expect(mocks.installManagedNpmUpdate).toHaveBeenCalledWith('2.0.0');
+    expect(process.env['QWEN_CODE_MANAGED_NPM_UPDATE_VERSION']).toBeUndefined();
+    expect(mocks.main).not.toHaveBeenCalled();
+  });
+
   it('falls back to getCliVersion when CLI_VERSION is unset', async () => {
     delete process.env['CLI_VERSION'];
 
@@ -502,6 +530,254 @@ describe('bootstrap import boundaries', () => {
     expect(output).toBe(`${expectedVersion}\n`);
   });
 
+  it('resolves and pins managed updates from the configured home', () => {
+    const tempDir = mkdtempSync(path.join(tmpdir(), 'qwen-managed-npm-'));
+    const entryDir = path.join(tempDir, 'bootstrap');
+    const entryPath = path.join(entryDir, 'cli-entry.mjs');
+    const qwenHome = path.join(tempDir, 'custom', 'qwen');
+    try {
+      mkdirSync(entryDir, { recursive: true });
+      copyFileSync('../../scripts/cli-entry.js', entryPath);
+      const bootstrapId = createHash('sha256')
+        .update(realpathSync(entryPath))
+        .digest('hex')
+        .slice(0, 16);
+      const launcherRoot = path.join(qwenHome, 'updates', 'npm', bootstrapId);
+      const packageRoot = path.join(
+        launcherRoot,
+        'versions',
+        '2.0.0',
+        'node_modules',
+        '@qwen-code',
+        'qwen-code',
+      );
+      mkdirSync(packageRoot, { recursive: true });
+      writeFileSync(
+        path.join(entryDir, 'cli.js'),
+        "process.stdout.write(JSON.stringify({ build: 'base', pin: process.env.QWEN_CODE_MANAGED_NPM_PIN }));\n",
+      );
+      writeFileSync(
+        path.join(entryDir, 'package.json'),
+        JSON.stringify({
+          name: '@qwen-code/qwen-code',
+          version: '1.0.0',
+        }),
+      );
+      writeFileSync(
+        path.join(packageRoot, 'package.json'),
+        JSON.stringify({
+          name: '@qwen-code/qwen-code',
+          version: '2.0.0',
+        }),
+      );
+      writeFileSync(
+        path.join(packageRoot, 'cli.js'),
+        "process.stdout.write(JSON.stringify({ build: 'managed-2', managed: process.env.QWEN_CODE_MANAGED_NPM_UPDATE, launcher: process.env.QWEN_CODE_CLI, pin: process.env.QWEN_CODE_MANAGED_NPM_PIN, args: process.argv.slice(2) }));\n",
+      );
+      mkdirSync(launcherRoot, { recursive: true });
+      const bootstrapStat = statSync(entryPath);
+
+      mkdirSync(path.join(tempDir, '.qwen'), { recursive: true });
+      writeFileSync(
+        path.join(tempDir, '.qwen', '.env'),
+        '\uFEFFQWEN_HOME: ~\\custom\\qwen\n',
+      );
+      const childEnv: NodeJS.ProcessEnv = {
+        ...process.env,
+        HOME: tempDir,
+        USERPROFILE: tempDir,
+        TMPDIR: tempDir,
+        TEMP: tempDir,
+        TMP: tempDir,
+      };
+      delete childEnv['QWEN_HOME'];
+      delete childEnv['QWEN_CODE_MANAGED_NPM_PIN'];
+      const baseSession = JSON.parse(
+        execFileSync(process.execPath, [entryPath, '--prompt', 'hello'], {
+          encoding: 'utf8',
+          env: childEnv,
+        }),
+      ) as { build: string; pin: string };
+      expect(baseSession.build).toBe('base');
+
+      writeFileSync(
+        path.join(launcherRoot, 'active.json'),
+        JSON.stringify({
+          version: '2.0.0',
+          bootstrap: realpathSync(entryPath),
+          baseVersion: '1.0.0',
+          bootstrapCtimeMs: bootstrapStat.ctimeMs,
+        }),
+      );
+      expect(
+        JSON.parse(
+          execFileSync(process.execPath, [entryPath, '--prompt', 'hello'], {
+            encoding: 'utf8',
+            env: {
+              ...childEnv,
+              QWEN_CODE_MANAGED_NPM_PIN: baseSession.pin,
+            },
+          }),
+        ),
+      ).toMatchObject({ build: 'base' });
+      expect(
+        JSON.parse(
+          execFileSync(process.execPath, [entryPath, '--prompt', 'hello'], {
+            encoding: 'utf8',
+            env: { ...childEnv, QWEN_HOME: '' },
+          }),
+        ),
+      ).toMatchObject({ build: 'base' });
+
+      writeFileSync(
+        path.join(tempDir, '.qwen', '.env'),
+        `QWEN_HOME:${qwenHome}\n`,
+      );
+      expect(
+        JSON.parse(
+          execFileSync(process.execPath, [entryPath, '--prompt', 'hello'], {
+            encoding: 'utf8',
+            env: childEnv,
+          }),
+        ),
+      ).toMatchObject({ build: 'base' });
+      writeFileSync(
+        path.join(tempDir, '.qwen', '.env'),
+        `QWEN_HOME:   \nOTHER=${qwenHome}\n`,
+      );
+      expect(
+        JSON.parse(
+          execFileSync(process.execPath, [entryPath, '--prompt', 'hello'], {
+            encoding: 'utf8',
+            env: childEnv,
+          }),
+        ),
+      ).toMatchObject({ build: 'base' });
+      writeFileSync(
+        path.join(tempDir, '.qwen', '.env'),
+        '\uFEFFQWEN_HOME: ~\\custom\\qwen\n',
+      );
+      const output = execFileSync(
+        process.execPath,
+        [entryPath, '--prompt', 'hello'],
+        {
+          encoding: 'utf8',
+          env: childEnv,
+        },
+      );
+
+      const managedSession = JSON.parse(output) as {
+        build: string;
+        managed: string;
+        launcher: string;
+        pin: string;
+        args: string[];
+      };
+      expect(managedSession).toMatchObject({
+        build: 'managed-2',
+        managed: 'true',
+        launcher: realpathSync(entryPath),
+        args: ['--prompt', 'hello'],
+      });
+      writeFileSync(
+        path.join(launcherRoot, 'active.json'),
+        JSON.stringify({
+          version: '3.0.0',
+          bootstrap: realpathSync(entryPath),
+          baseVersion: '1.0.0',
+          bootstrapCtimeMs: bootstrapStat.ctimeMs,
+        }),
+      );
+      expect(
+        JSON.parse(
+          execFileSync(process.execPath, [entryPath, '--prompt', 'hello'], {
+            encoding: 'utf8',
+            env: {
+              ...childEnv,
+              QWEN_HOME: 'different-relative-home',
+              QWEN_CODE_MANAGED_NPM_PIN: managedSession.pin,
+            },
+          }),
+        ),
+      ).toMatchObject({ build: 'managed-2' });
+      writeFileSync(
+        path.join(launcherRoot, 'active.json'),
+        JSON.stringify({
+          version: '2.0.0',
+          bootstrap: realpathSync(entryPath),
+          baseVersion: '1.0.0',
+          bootstrapCtimeMs: bootstrapStat.ctimeMs,
+        }),
+      );
+
+      const emptyHomeRoot = path.join(tempDir, 'empty-home');
+      const emptyQwenHome = path.join(emptyHomeRoot, '.qwen');
+      mkdirSync(emptyQwenHome, { recursive: true });
+      renameSync(
+        path.join(qwenHome, 'updates'),
+        path.join(emptyQwenHome, 'updates'),
+      );
+      const emptyHomeEnv = {
+        ...childEnv,
+        HOME: '',
+        USERPROFILE: '',
+        HOMEDRIVE: '',
+        HOMEPATH: '',
+        TMPDIR: emptyHomeRoot,
+        TEMP: emptyHomeRoot,
+        TMP: emptyHomeRoot,
+      };
+      expect(
+        JSON.parse(
+          execFileSync(process.execPath, [entryPath, '--prompt', 'hello'], {
+            encoding: 'utf8',
+            env: emptyHomeEnv,
+          }),
+        ),
+      ).toMatchObject({
+        build: 'managed-2',
+        managed: 'true',
+        launcher: realpathSync(entryPath),
+        args: ['--prompt', 'hello'],
+      });
+
+      const replacement = `${entryPath}.replacement`;
+      copyFileSync(entryPath, replacement);
+      renameSync(replacement, entryPath);
+      utimesSync(entryPath, bootstrapStat.atime, bootstrapStat.mtime);
+      expect(statSync(entryPath).ctimeMs).not.toBe(bootstrapStat.ctimeMs);
+      expect(
+        JSON.parse(
+          execFileSync(process.execPath, [entryPath, '--prompt', 'hello'], {
+            encoding: 'utf8',
+            env: emptyHomeEnv,
+          }),
+        ),
+      ).toMatchObject({ build: 'base' });
+
+      writeFileSync(
+        path.join(entryDir, 'package.json'),
+        JSON.stringify({
+          name: '@qwen-code/qwen-code',
+          version: '3.0.0',
+        }),
+      );
+      expect(
+        JSON.parse(
+          execFileSync(process.execPath, [entryPath, '--prompt', 'hello'], {
+            encoding: 'utf8',
+            env: {
+              ...emptyHomeEnv,
+              QWEN_CODE_MANAGED_NPM_UPDATE: 'true',
+            },
+          }),
+        ),
+      ).toMatchObject({ build: 'base' });
+    } finally {
+      rmSync(tempDir, { recursive: true, force: true });
+    }
+  }, 60_000);
+
   it('falls through to cli.js when wrapper package.json lookup fails', () => {
     const tempDir = mkdtempSync(path.join(tmpdir(), 'qwen-cli-entry-'));
     const entryDir = path.join(tempDir, 'bin');
diff --git a/packages/cli/src/cli.ts b/packages/cli/src/cli.ts
index 56592777c72..e9743bbf0ea 100644
--- a/packages/cli/src/cli.ts
+++ b/packages/cli/src/cli.ts
@@ -339,6 +339,17 @@ async function parseYargsCommand(
 export async function runCliEntry(
   rawArgv: readonly string[] = process.argv.slice(2),
 ): Promise<void> {
+  const managedUpdateVersion =
+    process.env['QWEN_CODE_MANAGED_NPM_UPDATE_VERSION'];
+  if (managedUpdateVersion) {
+    delete process.env['QWEN_CODE_MANAGED_NPM_UPDATE_VERSION'];
+    const { installManagedNpmUpdate } = await import(
+      './utils/managed-npm-update.js'
+    );
+    await installManagedNpmUpdate(managedUpdateVersion);
+    return;
+  }
+
   const argv = normalizeServeFastPathArgv(rawArgv);
   const route = resolveBootstrapRoute(argv);
 
diff --git a/packages/cli/src/startup/startup-prefetch.test.ts b/packages/cli/src/startup/startup-prefetch.test.ts
index 5a278ff9581..21bf507dbce 100644
--- a/packages/cli/src/startup/startup-prefetch.test.ts
+++ b/packages/cli/src/startup/startup-prefetch.test.ts
@@ -128,6 +128,7 @@ describe('startupPrefetch', () => {
     });
     mockGetInstallationInfo.mockReturnValue({
       updateCommand: 'npm install -g @qwen-code/qwen-code@latest',
+      packageManager: 'npm',
       isStandalone: false,
     });
     mockRequestUpdateOnExit.mockReturnValue(true);
@@ -220,8 +221,9 @@ describe('startupPrefetch', () => {
     );
   });
 
-  it('defers an available update until the session exits', async () => {
+  it('installs npm updates in the background after first render', async () => {
     const config = makeConfig();
+    const settings = makeSettings();
     mockCheckForUpdatesDetailed.mockResolvedValue({
       status: 'update',
       info: {
@@ -230,19 +232,49 @@ describe('startupPrefetch', () => {
       },
     });
 
-    startPostRenderPrefetches(config, makeSettings());
+    startPostRenderPrefetches(config, settings);
 
     await vi.dynamicImportSettled();
 
-    expect(mockRequestUpdateOnExit).toHaveBeenCalledTimes(1);
-    expect(mockUpdateEventEmit).toHaveBeenCalledWith('update-info', {
-      message:
-        'Update available\nThe update will be installed after you exit this session.',
+    expect(mockHandleAutoUpdate).toHaveBeenCalledWith(
+      {
+        message: 'Update available',
+        update: { latest: '2.0.0' },
+      },
+      settings,
+      '/repo',
+    );
+    expect(mockRequestUpdateOnExit).not.toHaveBeenCalled();
+  });
+
+  it('keeps manual guidance for npm installs without an update command', async () => {
+    mockGetInstallationInfo.mockReturnValue({
+      packageManager: 'npm',
+      isGlobal: true,
+      updateMessage: 'Update requires sudo.',
+    });
+    mockCheckForUpdatesDetailed.mockResolvedValue({
+      status: 'update',
+      info: {
+        message: 'Update available',
+        update: { latest: '2.0.0' },
+      },
     });
+
+    startPostRenderPrefetches(makeConfig(), makeSettings());
+    await vi.dynamicImportSettled();
+
+    expect(mockHandleAutoUpdate).toHaveBeenCalledOnce();
+    expect(mockRequestUpdateOnExit).not.toHaveBeenCalled();
   });
 
-  it('prompts for an explicit update when no parent supervisor is available', async () => {
+  it('prompts non-npm installs when no parent supervisor is available', async () => {
     mockRequestUpdateOnExit.mockReturnValue(false);
+    mockGetInstallationInfo.mockReturnValue({
+      updateCommand: 'pnpm add -g @qwen-code/qwen-code@latest',
+      packageManager: 'pnpm',
+      isGlobal: true,
+    });
     mockCheckForUpdatesDetailed.mockResolvedValue({
       status: 'update',
       info: {
@@ -270,6 +302,7 @@ describe('startupPrefetch', () => {
     });
     mockGetInstallationInfo.mockReturnValue({
       updateCommand: 'standalone update',
+      packageManager: 'standalone',
       isStandalone: true,
       standaloneDir: '/tmp/qwen-code',
     });
diff --git a/packages/cli/src/startup/startup-prefetch.ts b/packages/cli/src/startup/startup-prefetch.ts
index cf92bba8b33..5124d457e67 100644
--- a/packages/cli/src/startup/startup-prefetch.ts
+++ b/packages/cli/src/startup/startup-prefetch.ts
@@ -196,6 +196,10 @@ export function startPostRenderPrefetches(
             return;
           }
           const installationInfo = getInstallationInfo(projectRoot, true);
+          if (installationInfo.packageManager === 'npm') {
+            void handleAutoUpdate(result.info, settings, projectRoot);
+            return;
+          }
           if (
             installationInfo.updateCommand ||
             (installationInfo.isStandalone && installationInfo.standaloneDir)
diff --git a/packages/cli/src/ui/AppContainer.tsx b/packages/cli/src/ui/AppContainer.tsx
index 293dd4cd028..6a4574df78c 100644
--- a/packages/cli/src/ui/AppContainer.tsx
+++ b/packages/cli/src/ui/AppContainer.tsx
@@ -3040,10 +3040,13 @@ export const AppContainer = (props: AppContainerProps) => {
     dialogsVisible,
     stickyTodosLayoutKey,
     liveAgentPanelLayoutKey,
-    // Composer height also shifts with these; without them the footer isn't
-    // re-measured during a streaming turn and the VP viewport bottom clips.
+    // Composer and update notification height also shift with these; without
+    // them the footer isn't re-measured during a streaming turn and the VP
+    // viewport bottom clips.
     // (elapsedTime/currentLoadingPhrase excluded: they tick without changing rows.)
     streamingState,
+    updateInfo,
+    agentViewState.activeView,
     embeddedShellFocused,
     messageQueue.length,
     isInputActive,
diff --git a/packages/cli/src/ui/components/Notifications.tsx b/packages/cli/src/ui/components/Notifications.tsx
index 59dec3cf894..c7e75c8fa1e 100644
--- a/packages/cli/src/ui/components/Notifications.tsx
+++ b/packages/cli/src/ui/components/Notifications.tsx
@@ -9,11 +9,10 @@ import { useAppContext } from '../contexts/AppContext.js';
 import { useUIState } from '../contexts/UIStateContext.js';
 import { theme } from '../semantic-colors.js';
 import { StreamingState } from '../types.js';
-import { UpdateNotification } from './UpdateNotification.js';
 
 export const Notifications = () => {
   const { startupWarnings } = useAppContext();
-  const { initError, streamingState, updateInfo } = useUIState();
+  const { initError, streamingState } = useUIState();
 
   const showStartupWarnings = startupWarnings.length > 0;
   const showInitError =
@@ -21,7 +20,6 @@ export const Notifications = () => {
 
   return (
     <>
-      {updateInfo && <UpdateNotification message={updateInfo.message} />}
       {showStartupWarnings && (
         <Box
           borderStyle="round"
diff --git a/packages/cli/src/ui/layouts/DefaultAppLayout.test.tsx b/packages/cli/src/ui/layouts/DefaultAppLayout.test.tsx
index 322b28d54f0..ea5b7308c4e 100644
--- a/packages/cli/src/ui/layouts/DefaultAppLayout.test.tsx
+++ b/packages/cli/src/ui/layouts/DefaultAppLayout.test.tsx
@@ -22,6 +22,12 @@ vi.mock('../components/MainContent.js', () => ({
   MainContent: () => <Text>MainContent</Text>,
 }));
 
+vi.mock('../components/UpdateNotification.js', () => ({
+  UpdateNotification: ({ message }: { message: string }) => (
+    <Text>{`UpdateNotification: ${message}`}</Text>
+  ),
+}));
+
 vi.mock('../components/DialogManager.js', () => ({
   DialogManager: () => (
     <Text>
@@ -140,6 +146,32 @@ describe('DefaultAppLayout', () => {
     );
   });
 
+  it('renders an update that arrives after startup above the composer', () => {
+    mockedUseAgentViewState.mockReturnValue({
+      activeView: 'main',
+      agents: new Map(),
+    });
+
+    const { lastFrame } = renderLayout({
+      ...baseUIState,
+      updateInfo: {
+        message: 'Update successful!',
+        update: {
+          latest: '0.20.0',
+          current: '0.19.12',
+          type: 'latest',
+          name: '@qwen-code/qwen-code',
+        },
+      },
+    });
+    const output = lastFrame() ?? '';
+
+    expect(output).toContain('UpdateNotification: Update successful!');
+    expect(output.indexOf('UpdateNotification')).toBeLessThan(
+      output.indexOf('Composer'),
+    );
+  });
+
   it('does not render sticky todo list when dialogs are visible', () => {
     mockedUseAgentViewState.mockReturnValue({
       activeView: 'main',
@@ -257,4 +289,30 @@ describe('DefaultAppLayout', () => {
     expect(output).toContain('AgentChatView');
     expect(output).toContain('AgentComposer');
   });
+
+  it('renders update notifications in an agent tab view', () => {
+    mockedUseAgentViewState.mockReturnValue({
+      activeView: 'agent-1',
+      agents: new Map([['agent-1', {}]]),
+    });
+
+    const { lastFrame } = renderLayout({
+      ...baseUIState,
+      updateInfo: {
+        message: 'Update successful!',
+        update: {
+          latest: '0.20.0',
+          current: '0.19.12',
+          type: 'latest',
+          name: '@qwen-code/qwen-code',
+        },
+      },
+    });
+    const output = lastFrame() ?? '';
+
+    expect(output).toContain('UpdateNotification: Update successful!');
+    expect(output.indexOf('UpdateNotification')).toBeLessThan(
+      output.indexOf('AgentComposer'),
+    );
+  });
 });
diff --git a/packages/cli/src/ui/layouts/DefaultAppLayout.tsx b/packages/cli/src/ui/layouts/DefaultAppLayout.tsx
index 76159ca1e3e..242c3238af4 100644
--- a/packages/cli/src/ui/layouts/DefaultAppLayout.tsx
+++ b/packages/cli/src/ui/layouts/DefaultAppLayout.tsx
@@ -8,6 +8,7 @@ import type React from 'react';
 import { useEffect, useRef } from 'react';
 import { Box } from 'ink';
 import { MainContent } from '../components/MainContent.js';
+import { UpdateNotification } from '../components/UpdateNotification.js';
 import { DialogManager } from '../components/DialogManager.js';
 import { Composer } from '../components/Composer.js';
 import { ExitWarning } from '../components/ExitWarning.js';
@@ -68,6 +69,9 @@ export const DefaultAppLayout: React.FC = () => {
           {/* Agent view: chat history + agent-specific composer */}
           <AgentChatView agentId={activeView} />
           <Box flexDirection="column" ref={uiState.mainControlsRef}>
+            {!uiState.dialogsVisible && uiState.updateInfo && (
+              <UpdateNotification message={uiState.updateInfo.message} />
+            )}
             <AgentComposer key={activeView} agentId={activeView} />
             <ExitWarning />
           </Box>
@@ -77,6 +81,9 @@ export const DefaultAppLayout: React.FC = () => {
           {/* Main view: conversation history + main composer / dialogs */}
           <MainContent />
           <Box flexDirection="column" ref={uiState.mainControlsRef}>
+            {!uiState.dialogsVisible && uiState.updateInfo && (
+              <UpdateNotification message={uiState.updateInfo.message} />
+            )}
             {uiState.dialogsVisible ? (
               <Box
                 marginX={2}
diff --git a/packages/cli/src/ui/layouts/ScreenReaderAppLayout.test.tsx b/packages/cli/src/ui/layouts/ScreenReaderAppLayout.test.tsx
index dbbfb8e2796..794fcb06b66 100644
--- a/packages/cli/src/ui/layouts/ScreenReaderAppLayout.test.tsx
+++ b/packages/cli/src/ui/layouts/ScreenReaderAppLayout.test.tsx
@@ -21,6 +21,12 @@ vi.mock('../components/MainContent.js', () => ({
   MainContent: () => <Text>MainContent</Text>,
 }));
 
+vi.mock('../components/UpdateNotification.js', () => ({
+  UpdateNotification: ({ message }: { message: string }) => (
+    <Text>{`UpdateNotification: ${message}`}</Text>
+  ),
+}));
+
 vi.mock('../components/DialogManager.js', () => ({
   DialogManager: () => (
     <Text>
@@ -120,6 +126,43 @@ describe('ScreenReaderAppLayout', () => {
     expect(output).toContain('DialogManager 1');
   });
 
+  it('renders update notifications when no dialog is visible', () => {
+    const { lastFrame } = renderLayout({
+      ...baseUIState,
+      updateInfo: {
+        message: 'Update successful!',
+        update: {
+          latest: '0.20.0',
+          current: '0.19.12',
+          type: 'latest',
+          name: '@qwen-code/qwen-code',
+        },
+      },
+    });
+
+    expect(lastFrame() ?? '').toContain(
+      'UpdateNotification: Update successful!',
+    );
+  });
+
+  it('does not render update notifications when dialogs are visible', () => {
+    const { lastFrame } = renderLayout({
+      ...baseUIState,
+      dialogsVisible: true,
+      updateInfo: {
+        message: 'Update successful!',
+        update: {
+          latest: '0.20.0',
+          current: '0.19.12',
+          type: 'latest',
+          name: '@qwen-code/qwen-code',
+        },
+      },
+    });
+
+    expect(lastFrame() ?? '').not.toContain('UpdateNotification');
+  });
+
   it('keeps a tall dialog within the terminal frame when constrained', () => {
     dialogManagerMockState.lineCount = 20;
     const terminalHeight = 8;
diff --git a/packages/cli/src/ui/layouts/ScreenReaderAppLayout.tsx b/packages/cli/src/ui/layouts/ScreenReaderAppLayout.tsx
index 91964376aa5..4ceedaf5c0a 100644
--- a/packages/cli/src/ui/layouts/ScreenReaderAppLayout.tsx
+++ b/packages/cli/src/ui/layouts/ScreenReaderAppLayout.tsx
@@ -7,6 +7,7 @@
 import type React from 'react';
 import { Box } from 'ink';
 import { Notifications } from '../components/Notifications.js';
+import { UpdateNotification } from '../components/UpdateNotification.js';
 import { MainContent } from '../components/MainContent.js';
 import { DialogManager } from '../components/DialogManager.js';
 import { Composer } from '../components/Composer.js';
@@ -39,6 +40,9 @@ export const ScreenReaderAppLayout: React.FC = () => {
 
   return (
     <Box flexDirection="column" width="90%" height="100%">
+      {!uiState.dialogsVisible && uiState.updateInfo && (
+        <UpdateNotification message={uiState.updateInfo.message} />
+      )}
       <Notifications />
       <Footer />
       <Box flexGrow={1} overflow="hidden">
diff --git a/packages/cli/src/ui/utils/updateCheck.test.ts b/packages/cli/src/ui/utils/updateCheck.test.ts
index 1d9a98f2852..080289c7b9f 100644
--- a/packages/cli/src/ui/utils/updateCheck.test.ts
+++ b/packages/cli/src/ui/utils/updateCheck.test.ts
@@ -31,6 +31,7 @@ describe('checkForUpdates', () => {
     vi.resetAllMocks();
     // Clear DEV environment variable before each test
     delete process.env['DEV'];
+    delete process.env['QWEN_CODE_MANAGED_NPM_UPDATE'];
   });
 
   afterEach(() => {
@@ -279,6 +280,26 @@ describe('checkForUpdates', () => {
     expect(run).not.toHaveBeenCalled();
   });
 
+  it('uses the global npm registry for managed background updates', async () => {
+    process.env['QWEN_CODE_MANAGED_NPM_UPDATE'] = 'true';
+    const run = vi.fn();
+    const canonicalize = vi.fn();
+
+    await expect(
+      isGlobalNpmInstallation(
+        '/home/user/.qwen/updates/npm/versions/2.0.0/dist/cli.js',
+        run as unknown as NonNullable<
+          Parameters<typeof isGlobalNpmInstallation>[1]
+        >,
+        canonicalize as unknown as NonNullable<
+          Parameters<typeof isGlobalNpmInstallation>[2]
+        >,
+      ),
+    ).resolves.toBe(true);
+    expect(run).not.toHaveBeenCalled();
+    expect(canonicalize).not.toHaveBeenCalled();
+  });
+
   it('resolves a bin symlink before matching the npm package path', async () => {
     const run = vi.fn().mockResolvedValue({
       stdout: '/usr/local/lib/node_modules\n',
diff --git a/packages/cli/src/ui/utils/updateCheck.ts b/packages/cli/src/ui/utils/updateCheck.ts
index af12a056375..e218388c4ab 100644
--- a/packages/cli/src/ui/utils/updateCheck.ts
+++ b/packages/cli/src/ui/utils/updateCheck.ts
@@ -97,6 +97,7 @@ export async function isGlobalNpmInstallation(
   run: typeof execFileAsync = execFileAsync,
   canonicalize: typeof realpath = realpath,
 ): Promise<boolean> {
+  if (process.env['QWEN_CODE_MANAGED_NPM_UPDATE'] === 'true') return true;
   if (!cliPath) return false;
   // Canonicalize before matching. The CLI can be launched through its global
   // bin symlink (e.g. `.../bin/qwen`), whose path carries no `node_modules`
diff --git a/packages/cli/src/utils/handleAutoUpdate.test.ts b/packages/cli/src/utils/handleAutoUpdate.test.ts
index f4c7fa06044..59b90d07123 100644
--- a/packages/cli/src/utils/handleAutoUpdate.test.ts
+++ b/packages/cli/src/utils/handleAutoUpdate.test.ts
@@ -163,58 +163,49 @@ describe('handleAutoUpdate', () => {
       packageManager: PackageManager.NPM,
     });
 
-    // Simulate successful execution
-    setTimeout(() => {
-      mockChildProcess.emit('close', 0);
-    }, 0);
-
     handleAutoUpdate(mockUpdateInfo, mockSettings, '/root', mockSpawn);
 
     expect(mockSpawn).toHaveBeenCalledOnce();
   });
 
   it('should emit "update-failed" when the update process fails', async () => {
-    await new Promise<void>((resolve) => {
-      mockGetInstallationInfo.mockReturnValue({
-        updateCommand: 'npm i -g @qwen-code/qwen-code@latest',
-        updateMessage: 'This is an additional message.',
-        isGlobal: false,
-        packageManager: PackageManager.NPM,
-      });
-
-      // Simulate failed execution
-      setTimeout(() => {
-        mockChildProcess.stderr.emit('data', 'An error occurred');
-        mockChildProcess.emit('close', 1);
-        resolve();
-      }, 0);
-
-      handleAutoUpdate(mockUpdateInfo, mockSettings, '/root', mockSpawn);
+    mockGetInstallationInfo.mockReturnValue({
+      updateCommand: 'npm i -g @qwen-code/qwen-code@latest',
+      updateMessage: 'This is an additional message.',
+      isGlobal: false,
+      packageManager: PackageManager.NPM,
     });
-
+    const update = handleAutoUpdate(
+      mockUpdateInfo,
+      mockSettings,
+      '/root',
+      mockSpawn,
+    )!;
+    mockChildProcess.stderr.emit('data', 'An error occurred');
+    mockChildProcess.emit('close', 1);
+
+    await expect(update).resolves.toBe(false);
     expect(emitSpy).toHaveBeenCalledWith('update-failed', {
       message: 'Automatic update failed. Please try updating manually.',
     });
   });
 
   it('should emit "update-failed" when the spawn function throws an error', async () => {
-    await new Promise<void>((resolve) => {
-      mockGetInstallationInfo.mockReturnValue({
-        updateCommand: 'npm i -g @qwen-code/qwen-code@latest',
-        updateMessage: 'This is an additional message.',
-        isGlobal: false,
-        packageManager: PackageManager.NPM,
-      });
-
-      // Simulate an error event
-      setTimeout(() => {
-        mockChildProcess.emit('error', new Error('Spawn error'));
-        resolve();
-      }, 0);
-
-      handleAutoUpdate(mockUpdateInfo, mockSettings, '/root', mockSpawn);
+    mockGetInstallationInfo.mockReturnValue({
+      updateCommand: 'npm i -g @qwen-code/qwen-code@latest',
+      updateMessage: 'This is an additional message.',
+      isGlobal: false,
+      packageManager: PackageManager.NPM,
     });
-
+    const update = handleAutoUpdate(
+      mockUpdateInfo,
+      mockSettings,
+      '/root',
+      mockSpawn,
+    )!;
+    mockChildProcess.emit('error', new Error('Spawn error'));
+
+    await expect(update).resolves.toBe(false);
     expect(emitSpy).toHaveBeenCalledWith('update-failed', {
       message: 'Automatic update failed. Please try updating manually.',
     });
@@ -233,14 +224,14 @@ describe('handleAutoUpdate', () => {
 
     expect(mockSpawn).toHaveBeenCalledWith(
       process.execPath,
-      [
-        expect.stringMatching(/npm-cli\.js$/),
-        'i',
-        '-g',
-        '@qwen-code/qwen-code@nightly',
-      ],
+      [process.argv[1]],
       {
-        stdio: ['pipe', 'ignore', 'pipe'],
+        detached: true,
+        env: expect.objectContaining({
+          QWEN_CODE_MANAGED_NPM_UPDATE_VERSION: '2.0.0-nightly',
+        }),
+        stdio: ['ignore', 'ignore', 'pipe'],
+        windowsHide: true,
       },
     );
   });
@@ -257,14 +248,14 @@ describe('handleAutoUpdate', () => {
 
     expect(mockSpawn).toHaveBeenCalledWith(
       process.execPath,
-      [
-        expect.stringMatching(/npm-cli\.js$/),
-        'install',
-        '-g',
-        '@qwen-code/qwen-code@2.0.0',
-      ],
+      [process.argv[1]],
       {
-        stdio: ['pipe', 'ignore', 'pipe'],
+        detached: true,
+        env: expect.objectContaining({
+          QWEN_CODE_MANAGED_NPM_UPDATE_VERSION: '2.0.0',
+        }),
+        stdio: ['ignore', 'ignore', 'pipe'],
+        windowsHide: true,
       },
     );
   });
@@ -289,27 +280,25 @@ describe('handleAutoUpdate', () => {
   });
 
   it('should emit "update-success" when the update process succeeds', async () => {
-    await new Promise<void>((resolve) => {
-      mockGetInstallationInfo.mockReturnValue({
-        updateCommand: 'npm i -g @qwen-code/qwen-code@latest',
-        updateMessage: 'This is an additional message.',
-        isGlobal: false,
-        packageManager: PackageManager.NPM,
-      });
-
-      // Simulate successful execution
-      setTimeout(() => {
-        mockChildProcess.emit('close', 0);
-        resolve();
-      }, 0);
-
-      handleAutoUpdate(mockUpdateInfo, mockSettings, '/root', mockSpawn);
+    mockGetInstallationInfo.mockReturnValue({
+      updateCommand: 'npm i -g @qwen-code/qwen-code@latest',
+      updateMessage: 'This is an additional message.',
+      isGlobal: false,
+      packageManager: PackageManager.NPM,
     });
+    const update = handleAutoUpdate(
+      mockUpdateInfo,
+      mockSettings,
+      '/root',
+      mockSpawn,
+    )!;
+    mockChildProcess.emit('close', 0);
+
+    await expect(update).resolves.toBe(true);
 
     expect(emitSpy).toHaveBeenCalledWith('update-success', {
       message:
-        'Update successful! Please restart Qwen Code to use the new version. ' +
-        'Switching model providers before restarting may not work correctly.',
+        'Update successful! The new version will be used on your next run.',
     });
   });
 });
@@ -475,9 +464,7 @@ describe('setUpdateHandler', () => {
     expect(addItem).toHaveBeenCalledWith(
       {
         type: MessageType.INFO,
-        text:
-          'Update successful! Please restart Qwen Code to use the new version. ' +
-          'Switching model providers before restarting may not work correctly.',
+        text: 'Update successful! The new version will be used on your next run.',
       },
       expect.any(Number),
     );
diff --git a/packages/cli/src/utils/handleAutoUpdate.ts b/packages/cli/src/utils/handleAutoUpdate.ts
index c302b48acc9..da4902106f7 100644
--- a/packages/cli/src/utils/handleAutoUpdate.ts
+++ b/packages/cli/src/utils/handleAutoUpdate.ts
@@ -7,7 +7,6 @@
 import type { UpdateObject } from '../ui/utils/updateCheck.js';
 import type { LoadedSettings } from '../config/settings.js';
 import {
-  getNpmCliPath,
   getInstallationInfo,
   PackageManager,
   resolveUpdateCommand,
@@ -25,8 +24,7 @@ import { createDebugLogger } from '@qwen-code/qwen-code-core';
 const debugLogger = createDebugLogger('AUTO_UPDATE');
 
 const UPDATE_SUCCESS_MESSAGE =
-  'Update successful! Please restart Qwen Code to use the new version. ' +
-  'Switching model providers before restarting may not work correctly.';
+  'Update successful! The new version will be used on your next run.';
 const UPDATE_FAILED_MESSAGE =
   'Automatic update failed. Please try updating manually.';
 
@@ -97,51 +95,68 @@ export function handleAutoUpdate(
   );
   const platform = os.platform();
   const isWindows = platform === 'win32';
-  const command =
-    installationInfo.packageManager === PackageManager.NPM
-      ? process.execPath
-      : isWindows
-        ? 'cmd.exe'
-        : 'bash';
-  const commandArgs =
-    installationInfo.packageManager === PackageManager.NPM
-      ? [
-          getNpmCliPath(process.execPath, platform),
-          ...updateCommand.split(' ').slice(1),
-        ]
-      : isWindows
-        ? ['/c', updateCommand]
-        : ['-c', updateCommand];
+  const isManagedNpmUpdate =
+    installationInfo.packageManager === PackageManager.NPM;
+  const command = isManagedNpmUpdate
+    ? process.execPath
+    : isWindows
+      ? 'cmd.exe'
+      : 'bash';
+  const commandArgs = isManagedNpmUpdate
+    ? [process.argv[1]!]
+    : isWindows
+      ? ['/c', updateCommand]
+      : ['-c', updateCommand];
   const updateProcess = spawnFn(command, commandArgs, {
-    stdio: ['pipe', 'ignore', 'pipe'],
+    ...(isManagedNpmUpdate
+      ? {
+          detached: true,
+          env: {
+            ...process.env,
+            QWEN_CODE_MANAGED_NPM_UPDATE_VERSION: info.update.latest,
+          },
+          stdio: ['ignore', 'ignore', 'pipe'] as const,
+          windowsHide: true,
+        }
+      : { stdio: ['pipe', 'ignore', 'pipe'] as const }),
   });
   let errorOutput = '';
-  updateProcess.stderr.on('data', (data) => {
+  updateProcess.stderr?.on('data', (data) => {
     errorOutput += data.toString();
   });
 
-  updateProcess.on('close', (code) => {
-    if (code === 0) {
-      updateEventEmitter.emit('update-success', {
-        message: t(UPDATE_SUCCESS_MESSAGE),
-      });
-    } else {
-      debugLogger.warn(
-        `Automatic update command failed: ${updateCommand}; stderr: ${errorOutput.trim()}`,
+  return new Promise<boolean>((resolve) => {
+    let settled = false;
+    const finish = (error?: unknown) => {
+      if (settled) return;
+      settled = true;
+      try {
+        if (error) throw error;
+        updateEventEmitter.emit('update-success', {
+          message: t(UPDATE_SUCCESS_MESSAGE),
+        });
+        resolve(true);
+      } catch (error) {
+        debugLogger.warn('Automatic update failed:', error);
+        updateEventEmitter.emit('update-failed', {
+          message: t(UPDATE_FAILED_MESSAGE),
+        });
+        resolve(false);
+      }
+    };
+    updateProcess.once('close', (code) => {
+      finish(
+        code === 0
+          ? undefined
+          : new Error(
+              `Command failed: ${updateCommand}; stderr: ${errorOutput.trim()}`,
+            ),
       );
-      updateEventEmitter.emit('update-failed', {
-        message: t(UPDATE_FAILED_MESSAGE),
-      });
-    }
-  });
-
-  updateProcess.on('error', (err) => {
-    debugLogger.warn('Automatic update command failed to start:', err);
-    updateEventEmitter.emit('update-failed', {
-      message: t(UPDATE_FAILED_MESSAGE),
+    });
+    updateProcess.once('error', (error) => {
+      finish(error);
     });
   });
-  return updateProcess;
 }
 
 export function setUpdateHandler(
diff --git a/packages/cli/src/utils/managed-npm-update.test.ts b/packages/cli/src/utils/managed-npm-update.test.ts
new file mode 100644
index 00000000000..bb23b0a13b3
--- /dev/null
+++ b/packages/cli/src/utils/managed-npm-update.test.ts
@@ -0,0 +1,350 @@
+/**
+ * @license
+ * Copyright 2026 Qwen Code
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import {
+  activateManagedNpmUpdate,
+  cleanupManagedNpmUpdate,
+  installManagedNpmUpdate,
+  prepareManagedNpmUpdate,
+} from './managed-npm-update.js';
+import { EventEmitter } from 'node:events';
+import type { spawn } from 'node:child_process';
+import { createHash } from 'node:crypto';
+
+const temporaryDirectories: string[] = [];
+
+function makeTemporaryDirectory(): string {
+  const directory = fs.mkdtempSync(path.join(os.tmpdir(), 'qwen-npm-update-'));
+  temporaryDirectories.push(directory);
+  return directory;
+}
+
+function writeInstallation(prefix: string, version: string): void {
+  const packageRoot = path.join(
+    prefix,
+    'node_modules',
+    '@qwen-code',
+    'qwen-code',
+  );
+  fs.mkdirSync(packageRoot, { recursive: true });
+  fs.writeFileSync(
+    path.join(packageRoot, 'package.json'),
+    JSON.stringify({ name: '@qwen-code/qwen-code', version }),
+  );
+  fs.writeFileSync(path.join(packageRoot, 'cli.js'), '');
+  fs.writeFileSync(
+    path.join(packageRoot, 'cli-entry.js'),
+    `if (process.argv.includes('--version')) process.stdout.write('${version}\\n'); else await import('./cli.js');\n`,
+  );
+}
+
+function writeBaseInstallation(root: string, version = '1.0.0'): string {
+  const packageRoot = path.join(
+    root,
+    'global',
+    'node_modules',
+    '@qwen-code',
+    'qwen-code',
+  );
+  const bootstrap = path.join(packageRoot, 'cli-entry.js');
+  fs.mkdirSync(path.dirname(bootstrap), { recursive: true });
+  fs.writeFileSync(
+    path.join(packageRoot, 'package.json'),
+    JSON.stringify({ name: '@qwen-code/qwen-code', version }),
+  );
+  fs.writeFileSync(bootstrap, 'global launcher');
+  return bootstrap;
+}
+
+beforeEach(() => {
+  vi.stubEnv('NPM_CONFIG_GLOBALCONFIG', '/global/npmrc');
+});
+
+afterEach(() => {
+  vi.unstubAllEnvs();
+  for (const directory of temporaryDirectories.splice(0)) {
+    fs.rmSync(directory, { recursive: true, force: true });
+  }
+});
+
+describe('managed npm update', () => {
+  it('stages an exact version for one launcher', () => {
+    const root = makeTemporaryDirectory();
+    const update = prepareManagedNpmUpdate(
+      '2.0.0',
+      writeBaseInstallation(root),
+      path.join(root, 'updates'),
+    );
+
+    expect(update.installArgs).toEqual([
+      'install',
+      '--globalconfig',
+      path.resolve('/global/npmrc'),
+      '--prefix',
+      update.stagingDir,
+      '--global=false',
+      '--no-save',
+      '--package-lock=false',
+      '--no-audit',
+      '--no-fund',
+      '@qwen-code/qwen-code@2.0.0',
+    ]);
+    expect(update.versionDir).toBe(
+      path.join(update.launcherRoot, 'versions', '2.0.0'),
+    );
+  });
+
+  it('activates a verified install without changing running files', async () => {
+    const root = makeTemporaryDirectory();
+    const bootstrap = writeBaseInstallation(root);
+    const runningChunk = path.join(root, 'running', 'old.js');
+    fs.mkdirSync(path.dirname(runningChunk));
+    fs.writeFileSync(runningChunk, 'old chunk');
+    const update = prepareManagedNpmUpdate(
+      '2.0.0',
+      bootstrap,
+      path.join(root, 'updates'),
+    );
+    writeInstallation(update.stagingDir, '2.0.0');
+
+    await activateManagedNpmUpdate(update, '2.0.0', bootstrap);
+
+    expect(fs.existsSync(update.versionDir)).toBe(true);
+    expect(
+      JSON.parse(
+        fs.readFileSync(path.join(update.launcherRoot, 'active.json'), 'utf8'),
+      ),
+    ).toMatchObject({
+      version: '2.0.0',
+      bootstrap: fs.realpathSync(bootstrap),
+      baseVersion: '1.0.0',
+    });
+    expect(fs.readFileSync(bootstrap, 'utf8')).toBe('global launcher');
+    expect(fs.readFileSync(runningChunk, 'utf8')).toBe('old chunk');
+  });
+
+  it('installs and activates inside the managed worker', async () => {
+    const root = makeTemporaryDirectory();
+    const bootstrap = writeBaseInstallation(root);
+    const updateRoot = path.join(root, 'updates');
+    vi.stubEnv('NPM_CONFIG_USERCONFIG', 'config/npmrc');
+    const spawnFn = vi.fn(
+      (
+        _command: string,
+        args: readonly string[],
+        _options: object,
+      ): ReturnType<typeof spawn> => {
+        const prefix = args[args.indexOf('--prefix') + 1]!;
+        writeInstallation(prefix, '2.0.0');
+        const child = new EventEmitter();
+        queueMicrotask(() => child.emit('close', 0));
+        return child as ReturnType<typeof spawn>;
+      },
+    );
+
+    await installManagedNpmUpdate(
+      '2.0.0',
+      bootstrap,
+      updateRoot,
+      spawnFn as unknown as typeof spawn,
+    );
+
+    expect(spawnFn).toHaveBeenCalledWith(
+      process.execPath,
+      [
+        expect.stringMatching(/npm-cli\.js$/),
+        'install',
+        '--globalconfig',
+        path.resolve('/global/npmrc'),
+        '--prefix',
+        expect.any(String),
+        '--global=false',
+        '--no-save',
+        '--package-lock=false',
+        '--no-audit',
+        '--no-fund',
+        '@qwen-code/qwen-code@2.0.0',
+      ],
+      expect.objectContaining({
+        env: expect.objectContaining({
+          NPM_CONFIG_USERCONFIG: path.resolve('config/npmrc'),
+        }),
+        stdio: ['ignore', 'ignore', 'inherit'],
+        timeout: 10 * 60_000,
+        windowsHide: true,
+      }),
+    );
+    expect(
+      JSON.parse(
+        fs.readFileSync(
+          path.join(
+            updateRoot,
+            createHash('sha256')
+              .update(fs.realpathSync(bootstrap))
+              .digest('hex')
+              .slice(0, 16),
+            'active.json',
+          ),
+          'utf8',
+        ),
+      ),
+    ).toMatchObject({ version: '2.0.0' });
+  });
+
+  it.each([
+    ['a mismatched package', '2.0.1', false, 'did not match'],
+    ['a failed smoke test', '2.0.0', true, 'Command failed'],
+  ])('rejects %s', async (_name, installed, brokenBundle, error) => {
+    const root = makeTemporaryDirectory();
+    const bootstrap = writeBaseInstallation(root);
+    const update = prepareManagedNpmUpdate(
+      '2.0.0',
+      bootstrap,
+      path.join(root, 'updates'),
+    );
+    writeInstallation(update.stagingDir, installed);
+    if (brokenBundle) {
+      fs.writeFileSync(
+        path.join(
+          update.stagingDir,
+          'node_modules',
+          '@qwen-code',
+          'qwen-code',
+          'cli.js',
+        ),
+        'this is not valid JavaScript !!!\n',
+      );
+    }
+
+    await expect(
+      activateManagedNpmUpdate(update, '2.0.0', bootstrap),
+    ).rejects.toThrow(error);
+    expect(fs.existsSync(path.join(update.launcherRoot, 'active.json'))).toBe(
+      false,
+    );
+  });
+
+  it('does not mask a global install that changes while staging', async () => {
+    const root = makeTemporaryDirectory();
+    const bootstrap = writeBaseInstallation(root);
+    const update = prepareManagedNpmUpdate(
+      '2.0.0',
+      bootstrap,
+      path.join(root, 'updates'),
+    );
+    writeInstallation(update.stagingDir, '2.0.0');
+    writeBaseInstallation(root, '1.1.0');
+
+    await expect(
+      activateManagedNpmUpdate(update, '2.0.0', bootstrap),
+    ).rejects.toThrow('changed during update');
+  });
+
+  it('replaces a higher pointer from an older global install', async () => {
+    const root = makeTemporaryDirectory();
+    const updateRoot = path.join(root, 'updates');
+    const bootstrap = writeBaseInstallation(root);
+    const oldUpdate = prepareManagedNpmUpdate('3.0.0', bootstrap, updateRoot);
+    writeInstallation(oldUpdate.stagingDir, '3.0.0');
+    await activateManagedNpmUpdate(oldUpdate, '3.0.0', bootstrap);
+
+    writeBaseInstallation(root, '2.0.0');
+    const newUpdate = prepareManagedNpmUpdate('2.1.0', bootstrap, updateRoot);
+    writeInstallation(newUpdate.stagingDir, '2.1.0');
+    await activateManagedNpmUpdate(newUpdate, '2.1.0', bootstrap);
+
+    expect(
+      JSON.parse(
+        fs.readFileSync(
+          path.join(newUpdate.launcherRoot, 'active.json'),
+          'utf8',
+        ),
+      ),
+    ).toMatchObject({ version: '2.1.0', baseVersion: '2.0.0' });
+  });
+
+  it('keeps the highest concurrently activated version', async () => {
+    const root = makeTemporaryDirectory();
+    const updateRoot = path.join(root, 'updates');
+    const bootstrap = writeBaseInstallation(root);
+    const older = prepareManagedNpmUpdate('2.0.0', bootstrap, updateRoot);
+    const newer = prepareManagedNpmUpdate('3.0.0', bootstrap, updateRoot);
+    writeInstallation(older.stagingDir, '2.0.0');
+    writeInstallation(newer.stagingDir, '3.0.0');
+
+    await Promise.all([
+      activateManagedNpmUpdate(older, '2.0.0', bootstrap),
+      activateManagedNpmUpdate(newer, '3.0.0', bootstrap),
+    ]);
+
+    const active = JSON.parse(
+      fs.readFileSync(path.join(newer.launcherRoot, 'active.json'), 'utf8'),
+    ) as { version: string };
+    expect(active.version).toBe('3.0.0');
+    expect(
+      fs.existsSync(path.join(newer.launcherRoot, 'versions', active.version)),
+    ).toBe(true);
+  });
+
+  it('reuses a valid payload activated concurrently for the same version', async () => {
+    const root = makeTemporaryDirectory();
+    const updateRoot = path.join(root, 'updates');
+    const bootstrap = writeBaseInstallation(root);
+    const first = prepareManagedNpmUpdate('2.0.0', bootstrap, updateRoot);
+    const second = prepareManagedNpmUpdate('2.0.0', bootstrap, updateRoot);
+    writeInstallation(first.stagingDir, '2.0.0');
+    writeInstallation(second.stagingDir, '2.0.0');
+
+    await Promise.all([
+      activateManagedNpmUpdate(first, '2.0.0', bootstrap),
+      activateManagedNpmUpdate(second, '2.0.0', bootstrap),
+    ]);
+
+    expect(
+      JSON.parse(
+        fs.readFileSync(path.join(first.launcherRoot, 'active.json'), 'utf8'),
+      ),
+    ).toMatchObject({ version: '2.0.0' });
+    expect(fs.existsSync(first.versionDir)).toBe(true);
+    expect(fs.existsSync(first.stagingDir)).toBe(false);
+    expect(fs.existsSync(second.stagingDir)).toBe(false);
+  });
+
+  it('isolates payloads for different launchers', async () => {
+    const root = makeTemporaryDirectory();
+    const updateRoot = path.join(root, 'updates');
+    const launcherRoots = new Set<string>();
+
+    for (const bootstrap of [
+      writeBaseInstallation(path.join(root, 'node-22')),
+      writeBaseInstallation(path.join(root, 'node-24')),
+    ]) {
+      const update = prepareManagedNpmUpdate('2.0.0', bootstrap, updateRoot);
+      writeInstallation(update.stagingDir, '2.0.0');
+      await activateManagedNpmUpdate(update, '2.0.0', bootstrap);
+      launcherRoots.add(update.launcherRoot);
+    }
+
+    expect(launcherRoots).toHaveLength(2);
+  });
+
+  it('removes a failed staging directory', async () => {
+    const root = makeTemporaryDirectory();
+    const update = prepareManagedNpmUpdate(
+      '2.0.0',
+      writeBaseInstallation(root),
+      path.join(root, 'updates'),
+    );
+
+    await cleanupManagedNpmUpdate(update);
+
+    expect(fs.existsSync(update.stagingDir)).toBe(false);
+  });
+});
diff --git a/packages/cli/src/utils/managed-npm-update.ts b/packages/cli/src/utils/managed-npm-update.ts
new file mode 100644
index 00000000000..9720f6f450b
--- /dev/null
+++ b/packages/cli/src/utils/managed-npm-update.ts
@@ -0,0 +1,318 @@
+/**
+ * @license
+ * Copyright 2026 Qwen Code
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { Storage } from '@qwen-code/qwen-code-core';
+import { execFile, execFileSync, spawn } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import * as fs from 'node:fs';
+import * as fsPromises from 'node:fs/promises';
+import * as path from 'node:path';
+import { promisify } from 'node:util';
+import lockfile from 'proper-lockfile';
+import semver from 'semver';
+import { getNpmCliPath } from './installationInfo.js';
+
+const PACKAGE_NAME = '@qwen-code/qwen-code';
+const execFileAsync = promisify(execFile);
+
+interface ManagedNpmUpdate {
+  stagingDir: string;
+  versionDir: string;
+  launcherRoot: string;
+  baseVersion: string;
+  bootstrapCtimeMs: number;
+  installArgs: string[];
+}
+
+function assertVersion(version: string): void {
+  if (semver.valid(version) !== version) {
+    throw new Error(`Invalid update version: ${version}`);
+  }
+}
+
+function packageDir(prefix: string): string {
+  return path.join(prefix, 'node_modules', '@qwen-code', 'qwen-code');
+}
+
+function resolveBootstrapPath(bootstrapPath?: string): string {
+  if (!bootstrapPath) {
+    throw new Error('Unable to identify the Qwen Code npm launcher');
+  }
+  return fs.realpathSync(bootstrapPath);
+}
+
+function launcherId(bootstrapPath: string): string {
+  return createHash('sha256').update(bootstrapPath).digest('hex').slice(0, 16);
+}
+
+function resolveNpmGlobalConfigPath(): string {
+  const configured = process.env['NPM_CONFIG_GLOBALCONFIG'];
+  if (configured) return path.resolve(configured);
+  const output = execFileSync(
+    process.execPath,
+    [
+      getNpmCliPath(process.execPath, process.platform),
+      'config',
+      'get',
+      'globalconfig',
+      '--global',
+    ],
+    { encoding: 'utf8', timeout: 10_000 },
+  ).trim();
+  if (!output || output === 'null' || output === 'undefined') {
+    throw new Error('Unable to resolve the global npm configuration');
+  }
+  return output;
+}
+
+function readBaseInstallation(bootstrapPath: string): {
+  version: string;
+  ctimeMs: number;
+} {
+  const manifest = JSON.parse(
+    fs.readFileSync(
+      path.join(path.dirname(bootstrapPath), 'package.json'),
+      'utf8',
+    ),
+  ) as { name?: unknown; version?: unknown };
+  if (manifest.name !== PACKAGE_NAME || typeof manifest.version !== 'string') {
+    throw new Error('Unable to identify the base Qwen Code npm installation');
+  }
+  return {
+    version: manifest.version,
+    ctimeMs: fs.statSync(bootstrapPath).ctimeMs,
+  };
+}
+
+async function validateInstallation(
+  prefix: string,
+  version: string,
+): Promise<void> {
+  const root = packageDir(prefix);
+  const manifest = JSON.parse(
+    await fsPromises.readFile(path.join(root, 'package.json'), 'utf8'),
+  ) as { name?: unknown; version?: unknown };
+  if (manifest.name !== PACKAGE_NAME || manifest.version !== version) {
+    throw new Error(
+      `Installed package did not match ${PACKAGE_NAME}@${version}`,
+    );
+  }
+  await fsPromises.access(path.join(root, 'cli.js'));
+}
+
+async function smokeTest(prefix: string): Promise<void> {
+  const env = { ...process.env };
+  delete env['CLI_VERSION'];
+  delete env['QWEN_CODE_RELAUNCH_ARGS'];
+  await execFileAsync(
+    process.execPath,
+    [path.join(packageDir(prefix), 'cli-entry.js'), '--help'],
+    { encoding: 'utf8', env, timeout: 10_000 },
+  );
+}
+
+async function readActiveVersion(
+  activeFile: string,
+  expected: {
+    bootstrap: string;
+    baseVersion: string;
+    bootstrapCtimeMs: number;
+  },
+): Promise<string | null> {
+  try {
+    const active = JSON.parse(
+      await fsPromises.readFile(activeFile, 'utf8'),
+    ) as {
+      version?: unknown;
+      bootstrap?: unknown;
+      baseVersion?: unknown;
+      bootstrapCtimeMs?: unknown;
+    };
+    return typeof active.version === 'string' &&
+      semver.valid(active.version) !== null &&
+      active.bootstrap === expected.bootstrap &&
+      active.baseVersion === expected.baseVersion &&
+      active.bootstrapCtimeMs === expected.bootstrapCtimeMs
+      ? active.version
+      : null;
+  } catch {
+    return null;
+  }
+}
+
+export function prepareManagedNpmUpdate(
+  version: string,
+  bootstrapPath = process.env['QWEN_CODE_CLI'],
+  updateRoot = process.env['QWEN_CODE_MANAGED_NPM_ROOT'] ??
+    path.join(Storage.getGlobalQwenDir(), 'updates', 'npm'),
+): ManagedNpmUpdate {
+  assertVersion(version);
+  const resolvedBootstrapPath = resolveBootstrapPath(bootstrapPath);
+  const base = readBaseInstallation(resolvedBootstrapPath);
+  const npmGlobalConfigPath = resolveNpmGlobalConfigPath();
+  const launcherRoot = path.join(updateRoot, launcherId(resolvedBootstrapPath));
+  const versionsDir = path.join(launcherRoot, 'versions');
+  fs.mkdirSync(versionsDir, { recursive: true });
+  const stagingDir = fs.mkdtempSync(
+    path.join(versionsDir, `.${version}-${process.pid}-`),
+  );
+  return {
+    stagingDir,
+    versionDir: path.join(versionsDir, version),
+    launcherRoot,
+    baseVersion: base.version,
+    bootstrapCtimeMs: base.ctimeMs,
+    installArgs: [
+      'install',
+      '--globalconfig',
+      npmGlobalConfigPath,
+      '--prefix',
+      stagingDir,
+      '--global=false',
+      '--no-save',
+      '--package-lock=false',
+      '--no-audit',
+      '--no-fund',
+      `${PACKAGE_NAME}@${version}`,
+    ],
+  };
+}
+
+export async function installManagedNpmUpdate(
+  version: string,
+  bootstrapPath = process.env['QWEN_CODE_CLI'],
+  updateRoot = process.env['QWEN_CODE_MANAGED_NPM_ROOT'] ??
+    path.join(Storage.getGlobalQwenDir(), 'updates', 'npm'),
+  spawnFn: typeof spawn = spawn,
+): Promise<void> {
+  const update = prepareManagedNpmUpdate(version, bootstrapPath, updateRoot);
+  const env = { ...process.env };
+  for (const key of ['NPM_CONFIG_USERCONFIG', 'npm_config_userconfig']) {
+    const configured = env[key];
+    if (configured) env[key] = path.resolve(configured);
+  }
+  try {
+    await new Promise<void>((resolve, reject) => {
+      const child = spawnFn(
+        process.execPath,
+        [
+          getNpmCliPath(process.execPath, process.platform),
+          ...update.installArgs,
+        ],
+        {
+          cwd: update.stagingDir,
+          env,
+          stdio: ['ignore', 'ignore', 'inherit'],
+          timeout: 10 * 60_000,
+          windowsHide: true,
+        },
+      );
+      child.once('error', reject);
+      child.once('close', (code) => {
+        if (code === 0) resolve();
+        else reject(new Error(`npm install exited with code ${code}`));
+      });
+    });
+    await activateManagedNpmUpdate(update, version, bootstrapPath);
+  } catch (error) {
+    await cleanupManagedNpmUpdate(update);
+    throw error;
+  }
+}
+
+export async function activateManagedNpmUpdate(
+  update: ManagedNpmUpdate,
+  version: string,
+  bootstrapPath = process.env['QWEN_CODE_CLI'],
+): Promise<void> {
+  assertVersion(version);
+  const resolvedBootstrapPath = resolveBootstrapPath(bootstrapPath);
+  if (
+    path.join(
+      path.dirname(update.launcherRoot),
+      launcherId(resolvedBootstrapPath),
+    ) !== update.launcherRoot
+  ) {
+    throw new Error('The npm update does not match the active launcher');
+  }
+
+  await validateInstallation(update.stagingDir, version);
+  await smokeTest(update.stagingDir);
+
+  const activeFile = path.join(update.launcherRoot, 'active.json');
+  const release = await lockfile.lock(activeFile, {
+    realpath: false,
+    stale: 30_000,
+    retries: { retries: 50, minTimeout: 20, maxTimeout: 100 },
+  });
+  try {
+    const base = readBaseInstallation(resolvedBootstrapPath);
+    if (
+      base.version !== update.baseVersion ||
+      base.ctimeMs !== update.bootstrapCtimeMs
+    ) {
+      throw new Error(
+        'The base Qwen Code npm installation changed during update',
+      );
+    }
+
+    const activeVersion = await readActiveVersion(activeFile, {
+      bootstrap: resolvedBootstrapPath,
+      baseVersion: base.version,
+      bootstrapCtimeMs: base.ctimeMs,
+    });
+    if (activeVersion && semver.gt(activeVersion, version)) {
+      try {
+        await validateInstallation(
+          path.join(update.launcherRoot, 'versions', activeVersion),
+          activeVersion,
+        );
+        await cleanupManagedNpmUpdate(update);
+        return;
+      } catch {
+        // Replace a pointer whose payload is missing or incomplete.
+      }
+    }
+
+    try {
+      await fsPromises.rename(update.stagingDir, update.versionDir);
+    } catch (error) {
+      if (!fs.existsSync(update.versionDir)) throw error;
+      await validateInstallation(update.versionDir, version);
+      await cleanupManagedNpmUpdate(update);
+    }
+
+    const temporaryActivePath = `${activeFile}.${process.pid}`;
+    try {
+      await fsPromises.writeFile(
+        temporaryActivePath,
+        JSON.stringify({
+          version,
+          bootstrap: resolvedBootstrapPath,
+          baseVersion: base.version,
+          bootstrapCtimeMs: base.ctimeMs,
+        }),
+        { mode: 0o600 },
+      );
+      await fsPromises.rename(temporaryActivePath, activeFile);
+    } finally {
+      await fsPromises.rm(temporaryActivePath, { force: true });
+    }
+  } finally {
+    await release();
+  }
+}
+
+export async function cleanupManagedNpmUpdate(
+  update: ManagedNpmUpdate,
+): Promise<void> {
+  await fsPromises
+    .rm(update.stagingDir, { recursive: true, force: true })
+    .catch(() => {});
+}
+
+// ponytail: immutable versions are retained because a live older session may
+// still import them; add measured, lease-based GC only if disk use warrants it.
diff --git a/packages/cli/src/utils/update-relaunch.test.ts b/packages/cli/src/utils/update-relaunch.test.ts
index 557bdb9823c..9cb9de772cd 100644
--- a/packages/cli/src/utils/update-relaunch.test.ts
+++ b/packages/cli/src/utils/update-relaunch.test.ts
@@ -6,7 +6,6 @@
 
 import { beforeEach, describe, expect, it, vi } from 'vitest';
 import type { LoadedSettings } from '../config/settings.js';
-import { EventEmitter } from 'node:events';
 
 const checkForUpdatesDetailed = vi.hoisted(() => vi.fn());
 const handleAutoUpdate = vi.hoisted(() => vi.fn());
@@ -43,8 +42,12 @@ describe('updateBeforeRelaunch', () => {
   });
 
   it('waits for the package-manager update before reporting success', async () => {
-    const updateProcess = new EventEmitter();
-    handleAutoUpdate.mockReturnValue(updateProcess);
+    let finishUpdate!: (success: boolean) => void;
+    handleAutoUpdate.mockReturnValue(
+      new Promise((resolve) => {
+        finishUpdate = resolve;
+      }),
+    );
 
     const update = updateBeforeRelaunch(settings, '/repo', false);
     await vi.waitFor(() => expect(handleAutoUpdate).toHaveBeenCalledTimes(1));
@@ -53,7 +56,7 @@ describe('updateBeforeRelaunch', () => {
       'Update successful! The new version will be used on your next run.',
     );
 
-    updateProcess.emit('close', 0);
+    finishUpdate(true);
     await expect(update).resolves.toBe(true);
 
     expect(writeStderrLine).toHaveBeenCalledWith(
@@ -67,12 +70,9 @@ describe('updateBeforeRelaunch', () => {
   ] as const)(
     'reports %s failure and returns %s',
     async (_source, relaunchOnFailure, expected) => {
-      const updateProcess = new EventEmitter();
-      handleAutoUpdate.mockReturnValue(updateProcess);
+      handleAutoUpdate.mockResolvedValue(false);
 
       const update = updateBeforeRelaunch(settings, '/repo', relaunchOnFailure);
-      await vi.waitFor(() => expect(handleAutoUpdate).toHaveBeenCalledTimes(1));
-      updateProcess.emit('close', 1);
       await expect(update).resolves.toBe(expected);
 
       expect(writeStderrLine).toHaveBeenCalledWith(
diff --git a/packages/cli/src/utils/update-relaunch.ts b/packages/cli/src/utils/update-relaunch.ts
index d618888b8dd..77d1bfcd979 100644
--- a/packages/cli/src/utils/update-relaunch.ts
+++ b/packages/cli/src/utils/update-relaunch.ts
@@ -59,17 +59,11 @@ export async function updateBeforeRelaunch(
         );
         return relaunchOnFailure;
       }
-      const updateProcess = handleAutoUpdate(
+      const success = await handleAutoUpdate(
         result.info,
         settings,
         projectRoot,
       );
-      const success = updateProcess
-        ? await new Promise<boolean>((resolve) => {
-            updateProcess.once('close', (code) => resolve(code === 0));
-            updateProcess.once('error', () => resolve(false));
-          })
-        : false;
       writeStderrLine(
         t(
           success
diff --git a/scripts/cli-entry.js b/scripts/cli-entry.js
index f4178b6b60c..413d1d9a6d0 100755
--- a/scripts/cli-entry.js
+++ b/scripts/cli-entry.js
@@ -9,7 +9,7 @@
 /**
  * Production bin entry wrapper.
  *
- * For most commands: launches dist/cli.js with --expose-gc so that
+ * For most commands: launches the bundled CLI with --expose-gc so that
  * global.gc() is available for the memory-pressure monitor's critical-tier
  * cleanup.
  *
@@ -60,13 +60,150 @@ if (isTopLevelVersion && process.env['CLI_VERSION']) {
   process.exit(0);
 }
 
-const { existsSync, realpathSync } = await import('node:fs');
+const { existsSync, readFileSync, realpathSync, statSync } = await import(
+  'node:fs'
+);
+const { createHash } = await import('node:crypto');
+const { homedir, tmpdir } = await import('node:os');
+const { parseEnv } = await import('node:util');
 const { fileURLToPath, pathToFileURL } = await import('node:url');
 const { delimiter, dirname, join, parse, resolve, sep } = await import(
   'node:path'
 );
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
+const currentEntryPath = realpathSync(fileURLToPath(import.meta.url));
+
+function getHomeDir() {
+  try {
+    return homedir() || tmpdir();
+  } catch {
+    return tmpdir();
+  }
+}
+
+function resolveQwenHome() {
+  const configured = process.env['QWEN_HOME'];
+  if (!configured) return join(getHomeDir(), '.qwen');
+  if (configured === '~') return getHomeDir();
+  if (configured.startsWith('~/') || configured.startsWith('~\\')) {
+    return join(
+      getHomeDir(),
+      ...configured
+        .slice(2)
+        .split(/[/\\]+/)
+        .filter(Boolean),
+    );
+  }
+  return resolve(configured);
+}
+
+function preResolveQwenHome() {
+  if (Object.hasOwn(process.env, 'QWEN_HOME')) return;
+  const home = getHomeDir();
+  for (const candidate of [join(home, '.qwen', '.env'), join(home, '.env')]) {
+    try {
+      const source = readFileSync(candidate, 'utf8')
+        .replace(/^\uFEFF/, '')
+        .replace(/^(\s*(?:export\s+)?QWEN_HOME):[^\S\r\n]+/gm, '$1=');
+      const configured = parseEnv(source)['QWEN_HOME'];
+      if (configured) {
+        process.env['QWEN_HOME'] = configured;
+        return;
+      }
+    } catch {
+      // Match the CLI's quiet handling of missing or invalid home env files.
+    }
+  }
+}
+
+delete process.env['QWEN_CODE_MANAGED_NPM_UPDATE'];
+preResolveQwenHome();
+
+function getManagedNpmPin() {
+  try {
+    const pin = JSON.parse(process.env['QWEN_CODE_MANAGED_NPM_PIN'] ?? '');
+    if (pin.bootstrap !== currentEntryPath) return undefined;
+    if (
+      typeof pin.updateRoot !== 'string' ||
+      resolve(pin.updateRoot) !== pin.updateRoot
+    ) {
+      return undefined;
+    }
+    if (pin.version === null) {
+      return { version: null, updateRoot: pin.updateRoot };
+    }
+    return typeof pin.version === 'string' &&
+      /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/.test(
+        pin.version,
+      )
+      ? { version: pin.version, updateRoot: pin.updateRoot }
+      : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+const managedNpmPin = getManagedNpmPin();
+const managedNpmUpdateRoot =
+  managedNpmPin?.updateRoot ?? join(resolveQwenHome(), 'updates', 'npm');
+
+function getManagedNpmInstallation() {
+  try {
+    if (managedNpmPin?.version === null) return undefined;
+    const launcherRoot = join(
+      managedNpmUpdateRoot,
+      createHash('sha256').update(currentEntryPath).digest('hex').slice(0, 16),
+    );
+    let version = managedNpmPin?.version;
+    if (version === undefined) {
+      const active = JSON.parse(
+        readFileSync(join(launcherRoot, 'active.json'), 'utf8'),
+      );
+      const basePackageJsonPath = [
+        join(__dirname, 'package.json'),
+        join(__dirname, '..', 'package.json'),
+      ].find((candidate) => existsSync(candidate));
+      if (!basePackageJsonPath) return undefined;
+      const basePackage = JSON.parse(readFileSync(basePackageJsonPath, 'utf8'));
+      if (
+        typeof active.version !== 'string' ||
+        !/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/.test(
+          active.version,
+        ) ||
+        typeof active.bootstrap !== 'string' ||
+        realpathSync(active.bootstrap) !== currentEntryPath ||
+        active.baseVersion !== basePackage.version ||
+        active.bootstrapCtimeMs !== statSync(currentEntryPath).ctimeMs
+      ) {
+        return undefined;
+      }
+      version = active.version;
+    }
+    const packageRoot = join(
+      launcherRoot,
+      'versions',
+      version,
+      'node_modules',
+      '@qwen-code',
+      'qwen-code',
+    );
+    const packageJsonPath = join(packageRoot, 'package.json');
+    const pkg = JSON.parse(readFileSync(packageJsonPath, 'utf8'));
+    const cliPath = join(packageRoot, 'cli.js');
+    if (
+      pkg.name !== '@qwen-code/qwen-code' ||
+      pkg.version !== version ||
+      !existsSync(cliPath)
+    ) {
+      return undefined;
+    }
+    process.env['QWEN_CODE_MANAGED_NPM_UPDATE'] = 'true';
+    return { cliPath, packageJsonPath, version };
+  } catch {
+    return undefined;
+  }
+}
 
 // The entry a subprocess should call to reach THIS build.
 //
@@ -81,9 +218,9 @@ const __dirname = dirname(fileURLToPath(import.meta.url));
 // Assignment, not `||=`: an inherited value is another session's CLI — an outer
 // qwen shelling out to this one — and honouring it re-creates the exact skew above,
 // one level up. Each entry stamps itself, so nested sessions each call their own
-// build. Nothing downstream overwrites this: the spawn below runs dist/cli.js,
-// which never re-executes this wrapper, and the post-update relaunch re-enters
-// through the launcher's own wrapper — which stamps the updated entry, as it must.
+// build. The managed-version pin keeps nested calls on the running session's build
+// even if a background update changes the active pointer. A post-update relaunch
+// clears that pin so the launcher's wrapper selects the newly active build.
 //
 // One exception, and it points the SAME way: the standalone package launches this
 // file through a shim (`bin/qwen`) that selects the BUNDLED Node — the host may
@@ -98,19 +235,33 @@ const __dirname = dirname(fileURLToPath(import.meta.url));
 // wearing this one's stamp.
 const standaloneShim = process.env['QWEN_CODE_LAUNCHER_PATH'];
 delete process.env['QWEN_CODE_LAUNCHER_PATH'];
-process.env['QWEN_CODE_CLI'] =
-  standaloneShim && existsSync(standaloneShim)
-    ? standaloneShim
-    : fileURLToPath(import.meta.url);
 
+const managedNpmInstallation = getManagedNpmInstallation();
+const validStandaloneShim =
+  standaloneShim && existsSync(standaloneShim) ? standaloneShim : undefined;
+process.env['QWEN_CODE_CLI'] =
+  validStandaloneShim ?? fileURLToPath(import.meta.url);
+if (validStandaloneShim) {
+  delete process.env['QWEN_CODE_MANAGED_NPM_PIN'];
+  delete process.env['QWEN_CODE_MANAGED_NPM_ROOT'];
+} else {
+  process.env['QWEN_CODE_MANAGED_NPM_ROOT'] = managedNpmUpdateRoot;
+  process.env['QWEN_CODE_MANAGED_NPM_PIN'] = JSON.stringify({
+    bootstrap: currentEntryPath,
+    version: managedNpmInstallation?.version ?? null,
+    updateRoot: managedNpmUpdateRoot,
+  });
+}
 const cliPathCandidates = [
+  managedNpmInstallation?.cliPath,
   join(__dirname, 'cli.js'),
   join(__dirname, '..', 'dist', 'cli.js'),
-];
+].filter(Boolean);
 const packageJsonPathCandidates = [
+  managedNpmInstallation?.packageJsonPath,
   join(__dirname, 'package.json'),
   join(__dirname, '..', 'package.json'),
-];
+].filter(Boolean);
 const cliPath =
   cliPathCandidates.find((candidate) => existsSync(candidate)) ??
   cliPathCandidates[0];
@@ -193,7 +344,7 @@ if (isInProcessFastPath()) {
   } else {
     if (!launcher) {
       process.stderr.write(
-        'Update installed. Restart Qwen Code to use the new version.\n',
+        'Update successful! The new version will be used on your next run.\n',
       );
       process.exit(0);
     }
@@ -202,6 +353,7 @@ if (isInProcessFastPath()) {
       QWEN_CODE_RELAUNCH_ARGS: JSON.stringify(cliArgs),
       QWEN_CODE_SKIP_UPDATE_CHECK_ONCE: 'true',
     };
+    delete relaunchEnv['QWEN_CODE_MANAGED_NPM_PIN'];
     const relaunchResult =
       process.platform === 'win32' && launcher.endsWith('.cmd')
         ? spawnSync(
diff --git a/scripts/tests/cli-entry.test.js b/scripts/tests/cli-entry.test.js
index 2dbfe1abe8f..830b104be0c 100644
--- a/scripts/tests/cli-entry.test.js
+++ b/scripts/tests/cli-entry.test.js
@@ -6,21 +6,32 @@
 
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 
-const { spawnSyncMock, existsSyncMock } = vi.hoisted(() => ({
-  spawnSyncMock: vi.fn(() => ({ status: 0, signal: null })),
-  existsSyncMock: vi.fn(() => false),
-}));
+const { spawnSyncMock, existsSyncMock, homedirMock, tmpdirMock } = vi.hoisted(
+  () => ({
+    spawnSyncMock: vi.fn(() => ({ status: 0, signal: null })),
+    existsSyncMock: vi.fn(() => false),
+    homedirMock: vi.fn(() => '/home/test-user'),
+    tmpdirMock: vi.fn(() => '/tmp'),
+  }),
+);
 
 vi.mock('node:child_process', () => ({
   spawnSync: spawnSyncMock,
 }));
 
-vi.mock('node:fs', () => ({
+vi.mock('node:fs', async (importOriginal) => ({
+  ...(await importOriginal()),
   existsSync: existsSyncMock,
   realpathSync: vi.fn((p) => p),
   readFileSync: vi.fn(() => JSON.stringify({ version: '0.0.0-test' })),
 }));
 
+vi.mock('node:os', async (importOriginal) => ({
+  ...(await importOriginal()),
+  homedir: homedirMock,
+  tmpdir: tmpdirMock,
+}));
+
 const normalizePath = (path) => String(path).replaceAll('\\', '/');
 
 describe('scripts/cli-entry.js production entry', () => {
@@ -30,6 +41,8 @@ describe('scripts/cli-entry.js production entry', () => {
   beforeEach(() => {
     vi.resetModules();
     vi.clearAllMocks();
+    homedirMock.mockReturnValue('/home/test-user');
+    tmpdirMock.mockReturnValue('/tmp');
     // A non-fast-path command, so the entry takes the spawnSync branch (mocked)
     // instead of importing the real dist/cli.js in-process.
     process.argv = ['node', 'scripts/cli-entry.js', 'review', 'check'];
@@ -89,4 +102,21 @@ describe('scripts/cli-entry.js production entry', () => {
       else process.env.QWEN_CODE_LAUNCHER_PATH = inheritedShim;
     }
   });
+
+  it('falls back to tmpdir for tilde QWEN_HOME when homedir is unavailable', async () => {
+    const inheritedHome = process.env.QWEN_HOME;
+    homedirMock.mockImplementation(() => {
+      throw new Error('homedir unavailable');
+    });
+    process.env.QWEN_HOME = '~';
+    try {
+      await import('../cli-entry.js?tilde-home-fallback');
+      expect(normalizePath(process.env.QWEN_CODE_MANAGED_NPM_ROOT)).toBe(
+        '/tmp/updates/npm',
+      );
+    } finally {
+      if (inheritedHome === undefined) delete process.env.QWEN_HOME;
+      else process.env.QWEN_HOME = inheritedHome;
+    }
+  });
 });