fix(proxy): clarify shared port fallback and legacy 3456 handling

tests/e2e/proxy-command.e2e.test.ts

@@ -75,7 +75,7 @@ describe('proxy command e2e', () => {
     expect(help.status).toBe(0);
     expect(help.stdout).toContain('Usage: ccs proxy <start|stop|status|activate> [profile] [options]');
     expect(help.stdout).toContain('stop [profile]    Stop the running proxy (or all proxies when omitted)');
-    expect(help.stdout).toContain('Pin an exact local proxy port');
+    expect(help.stdout).toContain('Pin an exact local proxy port for this launch');
     expect(help.stdout).not.toContain('default: 3456');
   });
 

tests/integration/proxy/daemon-lifecycle.test.ts

@@ -9,6 +9,7 @@ import {
   startOpenAICompatProxy,
   stopOpenAICompatProxy,
 } from '../../../src/proxy/proxy-daemon';
+import { resolveOpenAICompatProxyPreferredPort } from '../../../src/proxy/proxy-port-resolver';
 import { resolveOpenAICompatProfileConfig } from '../../../src/proxy/profile-router';
 import {
   getLegacyOpenAICompatProxyPidPath,
@@ -345,6 +346,54 @@ describe('openai proxy daemon lifecycle', () => {
     }
   });
 
+  it('falls back when a configured shared proxy.port is occupied', async () => {
+    const occupiedPort = await getPort();
+    const server = Bun.serve({
+      port: occupiedPort,
+      hostname: '127.0.0.1',
+      fetch: () => new Response('busy'),
+    });
+
+    try {
+      mutateUnifiedConfig((config) => {
+        config.proxy = {
+          ...(config.proxy ?? {}),
+          port: occupiedPort,
+        };
+      });
+
+      const settingsPath = path.join(tempDir, 'shared-port.settings.json');
+      fs.writeFileSync(
+        settingsPath,
+        JSON.stringify({
+          env: {
+            ANTHROPIC_BASE_URL: 'http://127.0.0.1:11434',
+            ANTHROPIC_AUTH_TOKEN: 'ollama-shared-port',
+            ANTHROPIC_MODEL: 'qwen3-coder',
+            CCS_DROID_PROVIDER: 'generic-chat-completion-api',
+          },
+        }),
+        'utf8'
+      );
+
+      const profile = resolveOpenAICompatProfileConfig('shared-port', settingsPath, {
+        ANTHROPIC_BASE_URL: 'http://127.0.0.1:11434',
+        ANTHROPIC_AUTH_TOKEN: 'ollama-shared-port',
+        ANTHROPIC_MODEL: 'qwen3-coder',
+        CCS_DROID_PROVIDER: 'generic-chat-completion-api',
+      });
+      if (!profile) {
+        throw new Error('Expected shared-port OpenAI-compatible profile');
+      }
+
+      const started = await startOpenAICompatProxy(profile);
+      expect(started.success).toBe(true);
+      expect(started.port).not.toBe(occupiedPort);
+    } finally {
+      server.stop(true);
+    }
+  });
+
   it('keeps the existing proxy running if replacement startup fails', async () => {
     const firstPort = await getPort();
     const occupiedPort = await getPort();
@@ -394,8 +443,8 @@ describe('openai proxy daemon lifecycle', () => {
     }
   });
 
-  it('reuses the last-known port even when it is outside the default fallback range', async () => {
-    const preferredPort = await getPort();
+  it('returns to the adaptive canonical port after a stale fallback session', async () => {
+    const stalePort = await getPort();
     const settingsPath = path.join(tempDir, 'outside-range.settings.json');
     fs.writeFileSync(
       settingsPath,
@@ -428,7 +477,7 @@ describe('openai proxy daemon lifecycle', () => {
           profileName: profile.profileName,
           settingsPath: profile.settingsPath,
           host: '127.0.0.1',
-          port: preferredPort,
+          port: stalePort,
           baseUrl: profile.baseUrl,
           authToken: 'stale-token',
           model: profile.model,
@@ -441,7 +490,8 @@ describe('openai proxy daemon lifecycle', () => {
 
     const started = await startOpenAICompatProxy(profile);
     expect(started.success).toBe(true);
-    expect(started.port).toBe(preferredPort);
+    expect(started.port).toBe(resolveOpenAICompatProxyPreferredPort('outside-range'));
+    expect(started.port).not.toBe(stalePort);
   });
 
   it('does not keep a stopped shared-default profile anchored to legacy port 3456', async () => {

tests/unit/proxy/proxy-port-resolver.test.ts

@@ -5,6 +5,7 @@ import * as path from 'path';
 import { mutateUnifiedConfig } from '../../../src/config/unified-config-loader';
 import {
   resolveOpenAICompatProxyAdaptivePort,
+  resolveOpenAICompatProxyPortPreference,
   resolveOpenAICompatProxyPreferredPort,
 } from '../../../src/proxy/proxy-port-resolver';
 
@@ -39,7 +40,7 @@ describe('resolveOpenAICompatProxyPreferredPort', () => {
     expect(resolveOpenAICompatProxyPreferredPort('ccgm')).toBe(3461);
   });
 
-  it('preserves an explicit shared proxy port outside the adaptive default path', () => {
+  it('returns a configured shared proxy port as a shared preference', () => {
     mutateUnifiedConfig((config) => {
       config.proxy = {
         ...(config.proxy ?? {}),
@@ -48,10 +49,13 @@ describe('resolveOpenAICompatProxyPreferredPort', () => {
       };
     });
 
-    expect(resolveOpenAICompatProxyPreferredPort('ccg')).toBe(45_000);
+    expect(resolveOpenAICompatProxyPortPreference('ccg')).toEqual({
+      port: 45_000,
+      source: 'shared',
+    });
   });
 
-  it('preserves an explicit shared legacy 3456 port when the user configures it', () => {
+  it('treats legacy shared 3456 as an adaptive default on read', () => {
     mutateUnifiedConfig((config) => {
       config.proxy = {
         ...(config.proxy ?? {}),
@@ -60,7 +64,10 @@ describe('resolveOpenAICompatProxyPreferredPort', () => {
       };
     });
 
-    expect(resolveOpenAICompatProxyPreferredPort('ccg')).toBe(3456);
+    expect(resolveOpenAICompatProxyPortPreference('ccg')).toEqual({
+      port: resolveOpenAICompatProxyAdaptivePort('ccg'),
+      source: 'adaptive',
+    });
   });
 
   it('preserves an explicit shared 43456 port when the user configures it', () => {
@@ -72,14 +79,20 @@ describe('resolveOpenAICompatProxyPreferredPort', () => {
       };
     });
 
-    expect(resolveOpenAICompatProxyPreferredPort('ccg')).toBe(43_456);
+    expect(resolveOpenAICompatProxyPortPreference('ccg')).toEqual({
+      port: 43_456,
+      source: 'shared',
+    });
   });
 
   it('falls back to an adaptive shared default when no profile mapping exists', () => {
-    const preferredPort = resolveOpenAICompatProxyPreferredPort('ccg');
+    const portPreference = resolveOpenAICompatProxyPortPreference('ccg');
 
-    expect(preferredPort).toBe(resolveOpenAICompatProxyAdaptivePort('ccg'));
-    expect(preferredPort).not.toBe(3456);
+    expect(portPreference).toEqual({
+      port: resolveOpenAICompatProxyAdaptivePort('ccg'),
+      source: 'adaptive',
+    });
+    expect(resolveOpenAICompatProxyPreferredPort('ccg')).not.toBe(3456);
   });
 
   it('derives a stable adaptive default that does not keep all profiles on 3456', () => {