@plexor-dev/claude-code-plugin-staging 0.1.0-beta.15 → 0.1.0-beta.17

package/commands/plexor-agent.md

@@ -2,10 +2,35 @@
 description: Set Plexor agent autonomy — supervised, autonomous, or danger-full-auto (user)
 ---
 
-**RULE: Execute the bash command below EXACTLY ONCE. After the Bash tool returns output, your ONLY action is to present that output to the user. DO NOT re-execute the command. DO NOT call any other tools.**
+**Step 1: Check if arguments were provided.**
 
-Show current agent mode (no args) or set it (supervised, autonomous, danger-full-auto).
+If `$ARGUMENTS` contains a value (e.g., `/plexor-agent autonomous`), apply it directly:
 
 ```bash
 node ~/.claude/plugins/plexor/commands/plexor-agent.js $ARGUMENTS
 ```
+
+Present the output to the user and STOP. Do NOT call any other tools.
+
+**Step 2: If NO arguments were provided** (just `/plexor-agent`), first show the current state:
+
+```bash
+node ~/.claude/plugins/plexor/commands/plexor-agent.js
+```
+
+Then immediately use **AskUserQuestion** to let the user pick a mode:
+
+- **Question**: "Which agent autonomy mode?"
+- **Header**: "Agent mode"
+- **Options** (exactly 3):
+  1. **supervised** — "Confirm before every action"
+  2. **autonomous (Recommended)** — "Acts within safe bounds, default mode"
+  3. **danger-full-auto** — "Full autonomy, no guardrails"
+
+**Step 3: After the user selects**, apply their choice:
+
+```bash
+node ~/.claude/plugins/plexor/commands/plexor-agent.js <selected_value>
+```
+
+Present the output and STOP. Do NOT re-execute commands or call other tools.

package/commands/plexor-provider.js

@@ -74,9 +74,16 @@ function main() {
 
   config.settings = config.settings || {};
   config.settings.preferred_provider = requested;
+  if (requested !== 'auto') {
+    delete config.settings.preferred_model;
+    delete config.settings.preferredModel;
+  }
   if (!saveConfig(config)) { process.exit(1); }
 
   console.log(`Provider: ${current.value} → ${requested}`);
+  if (requested !== 'auto') {
+    console.log('  Cleared preferred_model to keep provider/model force hints mutually exclusive.');
+  }
   console.log(`  ${DESC[requested]}`);
   console.log('  Takes effect on next request.');
 }

package/commands/plexor-provider.md

@@ -2,10 +2,36 @@
 description: Set Plexor LLM provider — auto, anthropic, openai, deepseek, gemini, etc. (user)
 ---
 
-**RULE: Execute the bash command below EXACTLY ONCE. After the Bash tool returns output, your ONLY action is to present that output to the user. DO NOT re-execute the command. DO NOT call any other tools.**
+**Step 1: Check if arguments were provided.**
 
-Show current provider (no args) or set it (auto, anthropic, openai, deepseek, mistral, gemini, grok, cohere).
+If `$ARGUMENTS` contains a value (e.g., `/plexor-provider anthropic`), apply it directly:
 
 ```bash
 node ~/.claude/plugins/plexor/commands/plexor-provider.js $ARGUMENTS
 ```
+
+Present the output to the user and STOP. Do NOT call any other tools.
+
+**Step 2: If NO arguments were provided** (just `/plexor-provider`), first show the current state:
+
+```bash
+node ~/.claude/plugins/plexor/commands/plexor-provider.js
+```
+
+Then immediately use **AskUserQuestion** to let the user pick a provider:
+
+- **Question**: "Which LLM provider?"
+- **Header**: "Provider"
+- **Options** (exactly 4 — "Other" auto-covers mistral, gemini, grok, cohere):
+  1. **auto (Recommended)** — "Let Plexor choose the best provider automatically"
+  2. **anthropic** — "Claude models (Opus, Sonnet, Haiku)"
+  3. **openai** — "GPT models (GPT-4o, GPT-4.1, o1)"
+  4. **deepseek** — "DeepSeek models (Chat, Reasoner)"
+
+**Step 3: After the user selects**, apply their choice. If the user picks "Other", they will type the provider name (mistral, gemini, grok, cohere):
+
+```bash
+node ~/.claude/plugins/plexor/commands/plexor-provider.js <selected_value>
+```
+
+Present the output and STOP. Do NOT re-execute commands or call other tools.

package/commands/plexor-routing.md

@@ -2,10 +2,36 @@
 description: Set Plexor routing mode — eco, balanced, quality, or passthrough (user)
 ---
 
-**RULE: Execute the bash command below EXACTLY ONCE. After the Bash tool returns output, your ONLY action is to present that output to the user. DO NOT re-execute the command. DO NOT call any other tools.**
+**Step 1: Check if arguments were provided.**
 
-Show current routing mode (no args) or set it (eco, balanced, quality, passthrough).
+If `$ARGUMENTS` contains a value (e.g., `/plexor-routing eco`), apply it directly:
 
 ```bash
 node ~/.claude/plugins/plexor/commands/plexor-routing.js $ARGUMENTS
 ```
+
+Present the output to the user and STOP. Do NOT call any other tools.
+
+**Step 2: If NO arguments were provided** (just `/plexor-routing`), first show the current state:
+
+```bash
+node ~/.claude/plugins/plexor/commands/plexor-routing.js
+```
+
+Then immediately use **AskUserQuestion** to let the user pick a mode:
+
+- **Question**: "Which routing mode?"
+- **Header**: "Routing"
+- **Options** (exactly 4):
+  1. **eco (Recommended)** — "Cheapest models first, best cost efficiency"
+  2. **balanced** — "Balance cost and quality, smart model selection"
+  3. **quality** — "Premium models, best output quality"
+  4. **passthrough** — "Direct provider access, no routing logic"
+
+**Step 3: After the user selects**, apply their choice:
+
+```bash
+node ~/.claude/plugins/plexor/commands/plexor-routing.js <selected_value>
+```
+
+Present the output and STOP. Do NOT re-execute commands or call other tools.

package/commands/plexor-settings.js

@@ -127,6 +127,10 @@ function setDimension(dimension, value, config) {
 
   config.settings = config.settings || {};
   config.settings[configKey] = resolved;
+  if (configKey === 'preferred_provider' && resolved !== 'auto') {
+    delete config.settings.preferred_model;
+    delete config.settings.preferredModel;
+  }
   if (configKeyAlt && config.settings[configKeyAlt]) {
     delete config.settings[configKeyAlt];
   }
@@ -134,6 +138,9 @@ function setDimension(dimension, value, config) {
   if (!saveConfig(config)) { process.exit(1); }
 
   console.log(`${label} updated: ${current.value} → ${resolved}`);
+  if (configKey === 'preferred_provider' && resolved !== 'auto') {
+    console.log('  Cleared preferred_model to keep provider/model force hints mutually exclusive.');
+  }
   console.log(`  ${descMap[resolved]}`);
   console.log(`  Takes effect on next request.`);
 }

package/commands/plexor-settings.md

@@ -2,14 +2,51 @@
 description: View and change Plexor settings — routing mode, agent autonomy, LLM provider (user)
 ---
 
-**RULE: Execute the bash command below EXACTLY ONCE. After the Bash tool returns output, your ONLY action is to present that output to the user. DO NOT re-execute the command. DO NOT call any other tools.**
+**Step 1: Check if arguments were provided.**
 
-Show all settings (no args), or set a specific dimension:
-- `/plexor-settings` — dashboard
-- `/plexor-settings routing eco` — set routing mode
-- `/plexor-settings agent danger-full-auto` — set agent autonomy
-- `/plexor-settings provider anthropic` — set LLM provider
+If `$ARGUMENTS` contains both a dimension AND a value (e.g., `/plexor-settings routing eco`), apply it directly:
 
 ```bash
 node ~/.claude/plugins/plexor/commands/plexor-settings.js $ARGUMENTS
 ```
+
+Present the output to the user and STOP. Do NOT call any other tools.
+
+**Step 2: If only a dimension was provided** (e.g., `/plexor-settings routing`), show current state then present a picker for that dimension:
+
+```bash
+node ~/.claude/plugins/plexor/commands/plexor-settings.js $ARGUMENTS
+```
+
+Then use **AskUserQuestion** based on which dimension:
+
+**If dimension is "routing":**
+- **Question**: "Which routing mode?"
+- **Header**: "Routing"
+- **Options**: eco (Recommended) — "Cheapest first", balanced — "Cost/quality balance", quality — "Premium models", passthrough — "Direct access"
+
+**If dimension is "agent":**
+- **Question**: "Which agent autonomy mode?"
+- **Header**: "Agent mode"
+- **Options**: supervised — "Confirm every action", autonomous (Recommended) — "Safe bounds", danger-full-auto — "No guardrails"
+
+**If dimension is "provider":**
+- **Question**: "Which LLM provider?"
+- **Header**: "Provider"
+- **Options**: auto (Recommended) — "Auto-select", anthropic — "Claude models", openai — "GPT models", deepseek — "DeepSeek models"
+
+After the user selects, apply:
+
+```bash
+node ~/.claude/plugins/plexor/commands/plexor-settings.js <dimension> <selected_value>
+```
+
+Present the output and STOP.
+
+**Step 3: If NO arguments were provided** (just `/plexor-settings`), show the dashboard:
+
+```bash
+node ~/.claude/plugins/plexor/commands/plexor-settings.js
+```
+
+Present the output to the user and STOP. Do NOT call any other tools.

package/hooks/intercept.js

@@ -54,6 +54,8 @@ const VALID_PROVIDER_HINTS = new Set([
   'cohere'
 ]);
 
+const DISABLED_MODEL_HINTS = new Set(['auto', 'none', 'off']);
+
 function normalizeOrchestrationMode(mode) {
   if (typeof mode !== 'string') {
     return null;
@@ -62,8 +64,6 @@ function normalizeOrchestrationMode(mode) {
   if (!VALID_ORCHESTRATION_MODES.has(normalized)) {
     return null;
   }
-  // Accept legacy 'full-auto' as alias for 'danger-full-auto'
-  if (normalized === 'full-auto') return 'danger-full-auto';
   return normalized;
 }
 
@@ -122,6 +122,42 @@ function resolvePreferredProvider(settings) {
   return cfgProvider || 'auto';
 }
 
+function normalizePreferredModel(model) {
+  if (typeof model !== 'string') {
+    return null;
+  }
+  const trimmed = model.trim();
+  if (!trimmed) {
+    return null;
+  }
+  if (DISABLED_MODEL_HINTS.has(trimmed.toLowerCase())) {
+    return null;
+  }
+  return trimmed;
+}
+
+function resolvePreferredModel(settings) {
+  const envModel = normalizePreferredModel(
+    process.env.PLEXOR_MODEL || process.env.PLEXOR_PREFERRED_MODEL
+  );
+  if (envModel) {
+    return envModel;
+  }
+  const cfgModel = normalizePreferredModel(settings?.preferredModel || settings?.preferred_model);
+  return cfgModel || null;
+}
+
+function validateForceHintSelection(preferredProvider, preferredModel) {
+  if (!preferredModel || preferredProvider === 'auto') {
+    return;
+  }
+  const error = new Error(
+    'Invalid Plexor config: force only one hint. Set preferred_provider OR preferred_model, not both.'
+  );
+  error.code = 'PLEXOR_CONFIG_CONFLICT';
+  throw error;
+}
+
 // Try to load lib modules, fall back to inline implementations
 let ConfigManager, SessionManager, LocalCache, Logger, PlexorClient;
 let config, session, cache, logger;
@@ -143,10 +179,25 @@ try {
   const SESSION_PATH = path.join(process.env.HOME || '', '.plexor', 'session.json');
   const SESSION_TIMEOUT_MS = 30 * 60 * 1000;
 
+  const uxMessagesEnabled = !/^(0|false|no|off)$/i.test(
+    String(process.env.PLEXOR_UX_MESSAGES ?? process.env.PLEXOR_UX_DEBUG_MESSAGES ?? 'true')
+  );
+  const CYAN = '\x1b[36m';
+  const RESET = '\x1b[0m';
+  const formatUx = (msg) => {
+    const text = String(msg || '').trim();
+    if (!text) return '[PLEXOR: message]';
+    return text.startsWith('[PLEXOR:') ? text : `[PLEXOR: ${text}]`;
+  };
+
   logger = {
     debug: (msg) => process.env.PLEXOR_DEBUG && console.error(`[DEBUG] ${msg}`),
     info: (msg) => console.error(msg),
-    error: (msg) => console.error(`[ERROR] ${msg}`)
+    error: (msg) => console.error(`[ERROR] ${msg}`),
+    ux: (msg) => {
+      if (!uxMessagesEnabled) return;
+      console.error(`${CYAN}${formatUx(msg)}${RESET}`);
+    }
   };
 
   config = {
@@ -162,6 +213,7 @@ try {
           localCacheEnabled: cfg.settings?.localCacheEnabled ?? false,
           mode: cfg.settings?.mode || 'balanced',
           preferredProvider: cfg.settings?.preferred_provider || 'auto',
+          preferredModel: cfg.settings?.preferredModel || cfg.settings?.preferred_model || null,
           orchestrationMode:
             cfg.settings?.orchestrationMode || cfg.settings?.orchestration_mode || 'autonomous'
         };
@@ -277,6 +329,7 @@ async function main() {
     // not API requests and should not pollute session analytics
     if (isSlashCommand(request)) {
       logger.debug('Slash command detected, clean passthrough (no metadata)');
+      logger.ux('Slash command passthrough (no optimization applied)');
       return output(request);  // Completely clean — no metadata added
     }
 
@@ -284,6 +337,8 @@ async function main() {
     const orchestrationMode = resolveOrchestrationMode(settings);
     const gatewayMode = resolveGatewayMode(settings);
     const preferredProvider = resolvePreferredProvider(settings);
+    const preferredModel = resolvePreferredModel(settings);
+    validateForceHintSelection(preferredProvider, preferredModel);
 
     // Phase 3 Hypervisor Mode Detection
     // When ANTHROPIC_BASE_URL points to Plexor, all intelligence is server-side
@@ -295,10 +350,14 @@ async function main() {
       // HYPERVISOR MODE: Server handles everything
       // Just pass through with minimal metadata for session tracking
       logger.debug('Hypervisor mode active - server handles all optimization');
+      logger.ux(
+        `Hypervisor mode active (${gatewayMode}/${orchestrationMode}); routing handled server-side`
+      );
 
       // Add session tracking metadata (server will use this for analytics)
       return output({
         ...request,
+        ...(preferredModel ? { model: preferredModel } : {}),
         plexor_mode: gatewayMode,
         ...(preferredProvider !== 'auto' ? { plexor_provider: preferredProvider } : {}),
         plexor_orchestration_mode: orchestrationMode,
@@ -309,6 +368,7 @@ async function main() {
           orchestration_mode: orchestrationMode,
           plexor_mode: gatewayMode,
           preferred_provider: preferredProvider,
+          preferred_model: preferredModel,
           cwd: process.cwd(),
           timestamp: Date.now(),
         }
@@ -319,6 +379,7 @@ async function main() {
     // Azure CLI, AWS CLI, kubectl, etc. need tools to be preserved
     if (requiresToolExecution(request)) {
       logger.debug('CLI tool execution detected, passing through unchanged');
+      logger.ux('Tool-execution request detected; preserving tools via passthrough');
       session.recordPassthrough();
       return output({
         ...request,
@@ -337,6 +398,7 @@ async function main() {
     // Modifying messages breaks the agent loop and causes infinite loops
     if (isAgenticRequest(request)) {
       logger.debug('Agentic request detected, passing through unchanged');
+      logger.ux('Agentic/tool-use request detected; passthrough to avoid loop breakage');
       session.recordPassthrough();
       return output({
         ...request,
@@ -353,6 +415,7 @@ async function main() {
 
     if (!settings.enabled) {
       logger.debug('Plexor disabled, passing through');
+      logger.ux('Plexor plugin is disabled; forwarding request unchanged');
       session.recordPassthrough();
       return output({
         ...request,
@@ -367,6 +430,7 @@ async function main() {
 
     if (!settings.apiKey) {
       logger.info('Not authenticated. Run /plexor-login to enable optimization.');
+      logger.ux('Not authenticated. Run /plexor-login to enable Plexor routing');
       session.recordPassthrough();
       return output({
         ...request,
@@ -394,6 +458,7 @@ async function main() {
 
     if (cachedResponse && settings.localCacheEnabled) {
       logger.info('Local cache hit');
+      logger.ux('Local cache hit');
       session.recordCacheHit();
       return output({
         ...request,
@@ -422,9 +487,15 @@ async function main() {
     const savingsPercent = ((result.original_tokens - result.optimized_tokens) / result.original_tokens * 100).toFixed(1);
 
     logger.info(`Optimized: ${result.original_tokens} → ${result.optimized_tokens} tokens (${savingsPercent}% saved)`);
+    logger.ux(
+      `Optimized ${result.original_tokens} -> ${result.optimized_tokens} tokens (${savingsPercent}% saved)`
+    );
 
     if (result.recommended_provider !== 'anthropic') {
       logger.info(`Recommended: ${result.recommended_provider} (~$${result.estimated_cost.toFixed(4)})`);
+      logger.ux(
+        `Provider recommendation: ${result.recommended_provider} (~$${result.estimated_cost.toFixed(4)})`
+      );
     }
 
     const optimizedRequest = {
@@ -460,7 +531,15 @@ async function main() {
     return output(optimizedRequest);
 
   } catch (error) {
+    if (error?.code === 'PLEXOR_CONFIG_CONFLICT') {
+      logger.error(`Configuration error: ${error.message}`);
+      logger.ux(error.message);
+      process.stderr.write(`\n[Plexor] ${error.message}\n`);
+      process.exit(1);
+    }
+
     logger.error(`Error: ${error.message}`);
+    logger.ux(`Optimization hook error: ${error.message}`);
     logger.debug(error.stack);
 
     const errorRequestId = generateRequestId('error');  // Issue #701: Add request_id for tracking

package/hooks/track-response.js

@@ -133,6 +133,17 @@ try {
     async getMetadata() { return null; }
   };
 
+  const uxMessagesEnabled = !/^(0|false|no|off)$/i.test(
+    String(process.env.PLEXOR_UX_MESSAGES ?? process.env.PLEXOR_UX_DEBUG_MESSAGES ?? 'true')
+  );
+  const CYAN = '\x1b[36m';
+  const RESET = '\x1b[0m';
+  const formatUx = (msg) => {
+    const text = String(msg || '').trim();
+    if (!text) return '[PLEXOR: message]';
+    return text.startsWith('[PLEXOR:') ? text : `[PLEXOR: ${text}]`;
+  };
+
   Logger = class {
     constructor(name) { this.name = name; }
     info(msg, data) {
@@ -143,6 +154,10 @@ try {
       }
     }
     error(msg) { console.error(`[${this.name}] [ERROR] ${msg}`); }
+    ux(msg) {
+      if (!uxMessagesEnabled) return;
+      console.error(`${CYAN}${formatUx(msg)}${RESET}`);
+    }
     debug(msg) {
       if (process.env.PLEXOR_DEBUG) {
         console.error(`[${this.name}] [DEBUG] ${msg}`);
@@ -194,11 +209,17 @@ async function main() {
     input = await readStdin();
     response = JSON.parse(input);
 
+    // Normalize known Plexor recovery text into explicit [PLEXOR: ...] format
+    // and mirror high-signal UX hints to stderr in cyan.
+    response = normalizePlexorResponseMessages(response);
+    emitPlexorUxMessages(response);
+
     // Calculate output tokens for ALL responses (Issue #701)
     const outputTokens = estimateOutputTokens(response);
 
     // Get Plexor metadata if present
     const plexorMeta = response._plexor;
+    emitPlexorOutcomeSummary(response, plexorMeta, outputTokens);
 
     // Issue #701: Track ALL responses, not just when enabled
     // This ensures session stats are always accurate
@@ -374,3 +395,282 @@ main().catch((error) => {
   console.error(`[Plexor] Fatal error: ${error.message}`);
   process.exit(1);
 });
+
+function normalizePlexorText(text) {
+  if (typeof text !== 'string' || !text) {
+    return text;
+  }
+
+  let normalized = text;
+
+  if (
+    normalized.includes("I've been repeating the same operation without making progress.") &&
+    !normalized.includes("[PLEXOR: I've been repeating the same operation without making progress.]")
+  ) {
+    normalized = normalized.replace(
+      "I've been repeating the same operation without making progress.",
+      "[PLEXOR: I've been repeating the same operation without making progress.]"
+    );
+  }
+
+  normalized = normalized.replace(
+    /\[The repeated operation has been blocked\.[^\]]*\]/g,
+    (match) => `[PLEXOR: ${match.slice(1, -1)}]`
+  );
+  normalized = normalized.replace(
+    /\[All tasks have been completed\. Session ending\.\]/g,
+    '[PLEXOR: All tasks have been completed. Session ending.]'
+  );
+  normalized = normalized.replace(
+    /\[Blocked destructive cleanup command while recovering from prior errors\.[^\]]*\]/g,
+    (match) => `[PLEXOR: ${match.slice(1, -1)}]`
+  );
+
+  return normalized;
+}
+
+function normalizePlexorResponseMessages(response) {
+  if (!response || typeof response !== 'object') {
+    return response;
+  }
+
+  // Anthropic format
+  if (Array.isArray(response.content)) {
+    response.content = response.content.map((block) => {
+      if (!block || block.type !== 'text' || typeof block.text !== 'string') {
+        return block;
+      }
+      return { ...block, text: normalizePlexorText(block.text) };
+    });
+    return response;
+  }
+
+  // String content format
+  if (typeof response.content === 'string') {
+    response.content = normalizePlexorText(response.content);
+    return response;
+  }
+
+  // OpenAI choices format
+  if (Array.isArray(response.choices)) {
+    response.choices = response.choices.map((choice) => {
+      if (!choice || typeof choice !== 'object') return choice;
+      const updated = { ...choice };
+      if (typeof updated.text === 'string') {
+        updated.text = normalizePlexorText(updated.text);
+      }
+      if (updated.message && typeof updated.message.content === 'string') {
+        updated.message = {
+          ...updated.message,
+          content: normalizePlexorText(updated.message.content)
+        };
+      }
+      return updated;
+    });
+  }
+
+  return response;
+}
+
+function collectResponseText(response) {
+  const texts = [];
+  if (!response || typeof response !== 'object') {
+    return texts;
+  }
+
+  if (Array.isArray(response.content)) {
+    for (const block of response.content) {
+      if (block?.type === 'text' && typeof block.text === 'string') {
+        texts.push(block.text);
+      }
+    }
+  } else if (typeof response.content === 'string') {
+    texts.push(response.content);
+  }
+
+  if (Array.isArray(response.choices)) {
+    for (const choice of response.choices) {
+      if (typeof choice?.text === 'string') {
+        texts.push(choice.text);
+      }
+      if (typeof choice?.message?.content === 'string') {
+        texts.push(choice.message.content);
+      }
+    }
+  }
+
+  return texts;
+}
+
+function emitPlexorUxMessages(response) {
+  if (!logger || typeof logger.ux !== 'function') {
+    return;
+  }
+
+  const lines = collectResponseText(response).join('\n');
+  if (!lines) {
+    return;
+  }
+
+  const signals = new Set();
+
+  if (lines.includes("I've been repeating the same operation without making progress.")) {
+    signals.add("[PLEXOR: I've been repeating the same operation without making progress.]");
+  }
+  if (/repeated operation has been blocked/i.test(lines)) {
+    signals.add('[PLEXOR: The repeated operation has been blocked; switching approach.]');
+  }
+  if (/circuit breaker has fired/i.test(lines)) {
+    signals.add('[PLEXOR: Circuit breaker fired; recovery guidance active.]');
+  }
+  if (/blocked destructive cleanup command/i.test(lines)) {
+    signals.add('[PLEXOR: Blocked destructive cleanup command during recovery.]');
+  }
+  if (/all tasks have been completed\. session ending\./i.test(lines)) {
+    signals.add('[PLEXOR: All tasks completed; session ending.]');
+  }
+
+  const explicitPlexorMessages = lines.match(/\[PLEXOR:[^\]]+\]/g) || [];
+  for (const explicit of explicitPlexorMessages) {
+    signals.add(explicit);
+  }
+
+  for (const signal of signals) {
+    logger.ux(signal);
+  }
+}
+
+function toNumber(value) {
+  if (value === null || value === undefined || value === '') {
+    return null;
+  }
+  const parsed = typeof value === 'number' ? value : Number(value);
+  return Number.isFinite(parsed) ? parsed : null;
+}
+
+function toBoolean(value) {
+  if (typeof value === 'boolean') return value;
+  if (typeof value === 'string') {
+    const normalized = value.trim().toLowerCase();
+    if (['true', '1', 'yes', 'on'].includes(normalized)) return true;
+    if (['false', '0', 'no', 'off'].includes(normalized)) return false;
+  }
+  return null;
+}
+
+function formatUsd(value) {
+  if (value === null || value === undefined || !Number.isFinite(value)) {
+    return null;
+  }
+  return `$${value.toFixed(6)}`;
+}
+
+function extractGatewayOutcome(response, plexorMeta, outputTokens) {
+  const provider =
+    response?.plexor_provider_used ||
+    response?.plexor?.provider_used ||
+    plexorMeta?.recommended_provider ||
+    null;
+  const selectedModel =
+    response?.plexor_selected_model ||
+    response?.plexor?.selected_model ||
+    plexorMeta?.recommended_model ||
+    null;
+  const requestedModel = response?.model || null;
+  const routingSource = response?.plexor_routing_source || response?.plexor?.routing_source || null;
+  const authTier = response?.plexor_auth_tier || response?.plexor?.auth_tier || null;
+  const stopReason = response?.stop_reason || response?.choices?.[0]?.finish_reason || null;
+  const agentHalt = toBoolean(response?.plexor_agent_halt);
+  const fallbackUsed =
+    toBoolean(response?.plexor_fallback_used) ??
+    toBoolean(response?.fallback_used) ??
+    toBoolean(response?.plexor?.fallback_used);
+  const costUsd =
+    toNumber(response?.plexor_cost_usd) ??
+    toNumber(response?.cost_usd) ??
+    toNumber(plexorMeta?.estimated_cost) ??
+    null;
+  const savingsUsd =
+    toNumber(response?.plexor_savings_usd) ??
+    toNumber(response?.savings_usd) ??
+    null;
+  const inputTokens =
+    toNumber(response?.usage?.input_tokens) ??
+    toNumber(response?.usage?.prompt_tokens) ??
+    toNumber(plexorMeta?.optimized_tokens) ??
+    null;
+  const emittedOutputTokens =
+    toNumber(response?.usage?.output_tokens) ??
+    toNumber(response?.usage?.completion_tokens) ??
+    toNumber(outputTokens);
+
+  return {
+    provider,
+    selectedModel,
+    requestedModel,
+    routingSource,
+    authTier,
+    stopReason,
+    agentHalt,
+    fallbackUsed,
+    costUsd,
+    savingsUsd,
+    inputTokens,
+    emittedOutputTokens,
+  };
+}
+
+function emitPlexorOutcomeSummary(response, plexorMeta, outputTokens) {
+  if (!logger || typeof logger.ux !== 'function') {
+    return;
+  }
+
+  const outcome = extractGatewayOutcome(response, plexorMeta, outputTokens);
+  const messages = [];
+
+  if (outcome.provider || outcome.selectedModel || outcome.requestedModel) {
+    const parts = [];
+    if (outcome.provider) parts.push(`provider=${outcome.provider}`);
+    if (outcome.selectedModel) parts.push(`selected_model=${outcome.selectedModel}`);
+    if (!outcome.selectedModel && outcome.requestedModel) {
+      parts.push(`requested_model=${outcome.requestedModel}`);
+    }
+    if (outcome.routingSource) parts.push(`routing=${outcome.routingSource}`);
+    if (outcome.authTier) parts.push(`auth_tier=${outcome.authTier}`);
+    messages.push(`Routing summary: ${parts.join(' ')}`);
+  }
+
+  if (outcome.stopReason || outcome.agentHalt !== null || outcome.fallbackUsed !== null) {
+    const parts = [];
+    if (outcome.stopReason) parts.push(`stop_reason=${outcome.stopReason}`);
+    if (outcome.agentHalt === true) parts.push('agent_halt=auto_continue');
+    if (outcome.fallbackUsed !== null) parts.push(`fallback_used=${outcome.fallbackUsed}`);
+    if (parts.length > 0) {
+      messages.push(`Execution status: ${parts.join(' ')}`);
+    }
+  }
+
+  if (
+    outcome.costUsd !== null ||
+    outcome.savingsUsd !== null ||
+    outcome.inputTokens !== null ||
+    outcome.emittedOutputTokens !== null
+  ) {
+    const parts = [];
+    const costStr = formatUsd(outcome.costUsd);
+    const savingsStr = formatUsd(outcome.savingsUsd);
+    if (costStr) parts.push(`cost=${costStr}`);
+    if (savingsStr) parts.push(`savings=${savingsStr}`);
+    if (outcome.inputTokens !== null) parts.push(`input_tokens=${Math.round(outcome.inputTokens)}`);
+    if (outcome.emittedOutputTokens !== null) {
+      parts.push(`output_tokens=${Math.round(outcome.emittedOutputTokens)}`);
+    }
+    if (parts.length > 0) {
+      messages.push(`Usage summary: ${parts.join(' ')}`);
+    }
+  }
+
+  for (const msg of messages) {
+    logger.ux(msg);
+  }
+}

package/lib/config-utils.js

@@ -7,6 +7,50 @@ const path = require('path');
 const crypto = require('crypto');
 const { PLEXOR_DIR, CONFIG_PATH } = require('./constants');
 
+const DISABLED_HINT_VALUES = new Set(['', 'auto', 'none', 'off']);
+
+function normalizeForcedProvider(value) {
+  if (typeof value !== 'string') {
+    return null;
+  }
+  const normalized = value.trim().toLowerCase();
+  if (!normalized || normalized === 'auto') {
+    return 'auto';
+  }
+  return normalized;
+}
+
+function normalizeForcedModel(value) {
+  if (typeof value !== 'string') {
+    return null;
+  }
+  const normalized = value.trim();
+  if (!normalized || DISABLED_HINT_VALUES.has(normalized.toLowerCase())) {
+    return null;
+  }
+  return normalized;
+}
+
+function hasForcedHintConflict(config) {
+  const settings = config?.settings || {};
+  const provider = normalizeForcedProvider(
+    settings.preferred_provider ?? settings.preferredProvider ?? 'auto'
+  );
+  const model = normalizeForcedModel(settings.preferred_model ?? settings.preferredModel);
+  return Boolean(model) && provider !== 'auto';
+}
+
+function validateForcedHintConfig(config) {
+  if (!hasForcedHintConflict(config)) {
+    return { ok: true };
+  }
+  return {
+    ok: false,
+    message:
+      'Invalid Plexor config: set only one force hint. Use preferred_provider OR preferred_model, not both.'
+  };
+}
+
 function loadConfig() {
   try {
     if (!fs.existsSync(CONFIG_PATH)) {
@@ -31,6 +75,12 @@ function loadConfig() {
 
 function saveConfig(config) {
   try {
+    const validation = validateForcedHintConfig(config);
+    if (!validation.ok) {
+      console.error(`Error: ${validation.message}`);
+      return false;
+    }
+
     if (!fs.existsSync(PLEXOR_DIR)) {
       fs.mkdirSync(PLEXOR_DIR, { recursive: true, mode: 0o700 });
     }
@@ -71,4 +121,4 @@ function readSetting(config, configKey, configKeyAlt, envVar, validValues, defau
   return { value: defaultValue, source: 'default' };
 }
 
-module.exports = { loadConfig, saveConfig, readSetting };
+module.exports = { loadConfig, saveConfig, readSetting, hasForcedHintConflict, validateForcedHintConfig };

package/lib/config.js

@@ -5,6 +5,7 @@
 const fs = require('fs');
 const path = require('path');
 const { CONFIG_PATH, PLEXOR_DIR, DEFAULT_API_URL, DEFAULT_TIMEOUT } = require('./constants');
+const { validateForcedHintConfig } = require('./config-utils');
 
 class ConfigManager {
   constructor() {
@@ -23,6 +24,7 @@ class ConfigManager {
         localCacheEnabled: cfg.settings?.localCacheEnabled ?? false,
         mode: cfg.settings?.mode || 'balanced',
         preferredProvider: cfg.settings?.preferred_provider || 'auto',
+        preferredModel: cfg.settings?.preferredModel || cfg.settings?.preferred_model || null,
         orchestrationMode:
           cfg.settings?.orchestrationMode || cfg.settings?.orchestration_mode || 'autonomous'
       };
@@ -55,6 +57,11 @@ class ConfigManager {
           localCacheEnabled: config.localCacheEnabled ?? existing.settings?.localCacheEnabled,
           mode: config.mode ?? existing.settings?.mode,
           preferred_provider: config.preferredProvider ?? existing.settings?.preferred_provider,
+          preferred_model:
+            config.preferredModel ??
+            config.preferred_model ??
+            existing.settings?.preferredModel ??
+            existing.settings?.preferred_model,
           orchestrationMode:
             config.orchestrationMode ??
             config.orchestration_mode ??
@@ -63,6 +70,11 @@ class ConfigManager {
         }
       };
 
+      const validation = validateForcedHintConfig(updated);
+      if (!validation.ok) {
+        return false;
+      }
+
       fs.writeFileSync(this.configPath, JSON.stringify(updated, null, 2), { mode: 0o600 });
       return true;
     } catch {

package/lib/logger.js

@@ -12,6 +12,7 @@ const DIM = '\x1b[2m';
 const WHITE = '\x1b[37m';
 const YELLOW_FG = '\x1b[33m';
 const RED_FG = '\x1b[31m';
+const CYAN_FG = '\x1b[36m';
 const BLUE_BG = '\x1b[44m';
 const YELLOW_BG = '\x1b[43m';
 const RED_BG = '\x1b[41m';
@@ -21,10 +22,42 @@ const BADGE_INFO = `${BOLD}${WHITE}${BLUE_BG} PLEXOR ${RESET}`;
 const BADGE_WARN = `${BOLD}${WHITE}${YELLOW_BG} PLEXOR ${RESET}`;
 const BADGE_ERROR = `${BOLD}${WHITE}${RED_BG} PLEXOR ${RESET}`;
 
+function parseBooleanEnv(name, defaultValue) {
+  const raw = process.env[name];
+  if (raw === undefined || raw === null || raw === '') {
+    return defaultValue;
+  }
+  const normalized = String(raw).trim().toLowerCase();
+  if (['1', 'true', 'yes', 'on'].includes(normalized)) {
+    return true;
+  }
+  if (['0', 'false', 'no', 'off'].includes(normalized)) {
+    return false;
+  }
+  return defaultValue;
+}
+
+function formatUxMessage(message) {
+  const text = String(message || '').trim();
+  if (!text) {
+    return '[PLEXOR: message]';
+  }
+  if (text.startsWith('[PLEXOR:')) {
+    return text;
+  }
+  if (text.startsWith('[PLEXOR') && text.endsWith(']')) {
+    return text.replace(/^\[PLEXOR[^\]]*\]\s*/i, '[PLEXOR: ');
+  }
+  return `[PLEXOR: ${text}]`;
+}
+
 class Logger {
   constructor(component = 'plexor') {
     this.component = component;
-    this.debug_enabled = process.env.PLEXOR_DEBUG === '1' || process.env.PLEXOR_DEBUG === 'true';
+    this.debug_enabled = parseBooleanEnv('PLEXOR_DEBUG', false);
+    this.ux_messages_enabled =
+      parseBooleanEnv('PLEXOR_UX_MESSAGES', true) &&
+      parseBooleanEnv('PLEXOR_UX_DEBUG_MESSAGES', true);
   }
 
   debug(msg, data = null) {
@@ -48,6 +81,15 @@ class Logger {
     const output = data ? `${BADGE_ERROR} ${RED_FG}${msg} ${JSON.stringify(data)}${RESET}` : `${BADGE_ERROR} ${RED_FG}${msg}${RESET}`;
     console.error(output);
   }
+
+  ux(msg, data = null) {
+    if (!this.ux_messages_enabled) {
+      return;
+    }
+    const prefixed = formatUxMessage(msg);
+    const output = data ? `${prefixed} ${JSON.stringify(data)}` : prefixed;
+    console.error(`${CYAN_FG}${output}${RESET}`);
+  }
 }
 
 module.exports = Logger;

package/lib/settings-manager.js

@@ -23,6 +23,22 @@ const LOCK_TIMEOUT_MS = 5000; // 5 second lock timeout
 const PLEXOR_STAGING_URL = 'https://staging.api.plexor.dev/gateway/anthropic';
 const PLEXOR_PROD_URL = 'https://api.plexor.dev/gateway/anthropic';
 
+/**
+ * Check if a base URL is a Plexor-managed gateway URL.
+ * Detects all variants: production, staging, localhost, tunnels.
+ */
+function isManagedGatewayUrl(baseUrl) {
+  if (!baseUrl) return false;
+  return (
+    baseUrl.includes('plexor') ||
+    baseUrl.includes('staging.api') ||
+    baseUrl.includes('localhost') ||
+    baseUrl.includes('127.0.0.1') ||
+    baseUrl.includes('ngrok') ||
+    baseUrl.includes('localtunnel')
+  );
+}
+
 class ClaudeSettingsManager {
   constructor() {
     this.settingsPath = SETTINGS_PATH;
@@ -248,11 +264,8 @@ class ClaudeSettingsManager {
       const baseUrl = settings.env?.ANTHROPIC_BASE_URL || null;
       const hasToken = !!settings.env?.ANTHROPIC_AUTH_TOKEN;
 
-      // Check if routing to Plexor
-      const isPlexorRouting = baseUrl && (
-        baseUrl.includes('plexor') ||
-        baseUrl.includes('staging.api')
-      );
+      // Check if routing to Plexor (any variant: prod, staging, localhost, tunnel)
+      const isPlexorRouting = isManagedGatewayUrl(baseUrl);
 
       return {
         enabled: isPlexorRouting,
@@ -276,7 +289,7 @@ class ClaudeSettingsManager {
       const settings = this.load();
       const baseUrl = settings.env?.ANTHROPIC_BASE_URL || '';
       const authToken = settings.env?.ANTHROPIC_AUTH_TOKEN || '';
-      const isPlexorUrl = baseUrl.includes('plexor') || baseUrl.includes('staging.api');
+      const isPlexorUrl = isManagedGatewayUrl(baseUrl);
 
       if (isPlexorUrl && !authToken) {
         return { partial: true, issue: 'Plexor URL set but no auth token' };
@@ -345,6 +358,7 @@ const settingsManager = new ClaudeSettingsManager();
 module.exports = {
   ClaudeSettingsManager,
   settingsManager,
+  isManagedGatewayUrl,
   CLAUDE_DIR,
   SETTINGS_PATH,
   PLEXOR_STAGING_URL,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plexor-dev/claude-code-plugin-staging",
-  "version": "0.1.0-beta.15",
+  "version": "0.1.0-beta.17",
   "description": "STAGING - LLM cost optimization plugin for Claude Code (internal testing)",
   "main": "lib/constants.js",
   "bin": {

package/scripts/postinstall.js

@@ -13,42 +13,109 @@ const os = require('os');
 const { execSync } = require('child_process');
 
 /**
- * Get the correct home directory, accounting for sudo.
- * When running with sudo, os.homedir() returns /root, but we want
- * the actual user's home directory.
+ * Resolve the home directory for a given username by querying /etc/passwd.
+ * This is the authoritative source and handles non-standard home paths
+ * (e.g., /root, /opt/users/foo, NIS/LDAP users, etc.).
+ * Returns null if lookup fails (Windows, missing getent, etc.).
+ */
+function getHomeDirFromPasswd(username) {
+  try {
+    const entry = execSync(`getent passwd ${username}`, { encoding: 'utf8' }).trim();
+    // Format: username:x:uid:gid:gecos:homedir:shell
+    const fields = entry.split(':');
+    if (fields.length >= 6 && fields[5]) {
+      return fields[5];
+    }
+  } catch {
+    // getent not available or user not found
+  }
+  return null;
+}
+
+/**
+ * Get the correct home directory for the process's effective user.
+ *
+ * Handles three scenarios:
+ *   1. Normal execution:           HOME is correct, os.homedir() is correct.
+ *   2. `sudo npm install`:         SUDO_USER is set, os.homedir() returns /root,
+ *                                   but we want the SUDO_USER's home.
+ *   3. `sudo -u target npm install`:
+ *                                   HOME may still be the *caller's* home (e.g.,
+ *                                   /home/azureuser), SUDO_USER is the *caller*
+ *                                   (not the target), but process.getuid() returns
+ *                                   the *target* UID. We must resolve home from
+ *                                   /etc/passwd by UID.
+ *
+ * Resolution order (most authoritative first):
+ *   a) Look up the effective UID in /etc/passwd via getent (handles sudo -u)
+ *   b) Fall back to os.homedir() (works for normal execution)
+ *   c) Fall back to HOME / USERPROFILE env vars (last resort)
  */
 function getHomeDir() {
-  // Check if running with sudo - SUDO_USER contains the original username
-  if (process.env.SUDO_USER) {
-    // On Linux/Mac, home directories are typically /home/<user> or /Users/<user>
-    const platform = os.platform();
-    if (platform === 'darwin') {
-      return path.join('/Users', process.env.SUDO_USER);
-    } else if (platform === 'linux') {
-      return path.join('/home', process.env.SUDO_USER);
+  // On non-Windows, resolve via the effective UID's passwd entry.
+  // This is the most reliable method and correctly handles both
+  // `sudo` and `sudo -u <target>` scenarios.
+  if (os.platform() !== 'win32') {
+    try {
+      const uid = process.getuid();
+      const entry = execSync(`getent passwd ${uid}`, { encoding: 'utf8' }).trim();
+      const fields = entry.split(':');
+      if (fields.length >= 6 && fields[5]) {
+        return fields[5];
+      }
+    } catch {
+      // Fall through to other methods
     }
   }
-  return os.homedir();
+
+  // Fallback: os.homedir() (reads HOME env var, then passwd on Unix)
+  const home = os.homedir();
+  if (home) return home;
+
+  // Last resort: environment variables
+  return process.env.HOME || process.env.USERPROFILE || '/tmp';
 }
 
 /**
- * Get uid/gid for the target user (handles sudo case).
- * Returns null if not running with sudo or on Windows.
+ * Get uid/gid for the effective user running this process.
+ * Under `sudo`, the effective user is root but we want to chown to the
+ * original (SUDO_USER) or target (`sudo -u target`) user.
+ * Under `sudo -u target`, process.getuid() IS the target, so we use that.
+ * Returns null on Windows or if no privilege elevation detected.
  */
 function getTargetUserIds() {
-  const sudoUser = process.env.SUDO_USER;
-  if (!sudoUser || os.platform() === 'win32') {
+  if (os.platform() === 'win32') {
     return null;
   }
 
   try {
-    // Get uid and gid for the sudo user
-    const uid = parseInt(execSync(`id -u ${sudoUser}`, { encoding: 'utf8' }).trim(), 10);
-    const gid = parseInt(execSync(`id -g ${sudoUser}`, { encoding: 'utf8' }).trim(), 10);
-    return { uid, gid, user: sudoUser };
+    const effectiveUid = process.getuid();
+
+    // If we're running as root (uid 0), we were likely invoked via `sudo`.
+    // Chown files to SUDO_USER (the human who ran sudo).
+    if (effectiveUid === 0 && process.env.SUDO_USER) {
+      const uid = parseInt(execSync(`id -u ${process.env.SUDO_USER}`, { encoding: 'utf8' }).trim(), 10);
+      const gid = parseInt(execSync(`id -g ${process.env.SUDO_USER}`, { encoding: 'utf8' }).trim(), 10);
+      return { uid, gid, user: process.env.SUDO_USER };
+    }
+
+    // If we're NOT root but SUDO_USER is set, we were invoked via `sudo -u target`.
+    // The effective UID is already the target user. Chown to that user.
+    if (effectiveUid !== 0 && process.env.SUDO_USER) {
+      const entry = execSync(`getent passwd ${effectiveUid}`, { encoding: 'utf8' }).trim();
+      const fields = entry.split(':');
+      if (fields.length >= 4) {
+        const username = fields[0];
+        const uid = parseInt(fields[2], 10);
+        const gid = parseInt(fields[3], 10);
+        return { uid, gid, user: username };
+      }
+    }
   } catch {
-    return null;
+    // Fall through
   }
+
+  return null;
 }
 
 /**
@@ -77,33 +144,71 @@ const PLEXOR_LIB_DIR = path.join(HOME_DIR, '.claude', 'plugins', 'plexor', 'lib'
 const PLEXOR_CONFIG_DIR = path.join(HOME_DIR, '.plexor');
 const PLEXOR_CONFIG_FILE = path.join(PLEXOR_CONFIG_DIR, 'config.json');
 
+/**
+ * Check if a base URL is a Plexor-managed gateway URL.
+ * Detects all variants: production, staging, localhost, tunnels.
+ */
+function isManagedGatewayUrl(baseUrl) {
+  if (!baseUrl) return false;
+  return (
+    baseUrl.includes('plexor') ||
+    baseUrl.includes('staging.api') ||
+    baseUrl.includes('localhost') ||
+    baseUrl.includes('127.0.0.1') ||
+    baseUrl.includes('ngrok') ||
+    baseUrl.includes('localtunnel')
+  );
+}
+
+/**
+ * The expected base URL for THIS plugin variant.
+ * Used to detect when a different variant was previously installed.
+ */
+const THIS_VARIANT_URL = 'https://staging.api.plexor.dev/gateway/anthropic';
+
 /**
  * Check for orphaned Plexor routing in settings.json without valid config.
- * This can happen if a previous uninstall was incomplete.
+ * Also detects variant mismatch (e.g., localhost plugin was installed, now
+ * installing staging plugin) and migrates ANTHROPIC_BASE_URL + fixes
+ * ANTHROPIC_API_KEY → ANTHROPIC_AUTH_TOKEN (#2174).
  */
 function checkOrphanedRouting() {
-  const home = process.env.HOME || process.env.USERPROFILE;
-  if (!home) return;
-
-  const settingsPath = path.join(home, '.claude', 'settings.json');
-  const configPath = path.join(home, '.plexor', 'config.json');
+  // Use the resolved HOME_DIR (not process.env.HOME which may be wrong under sudo -u)
+  const settingsPath = path.join(HOME_DIR, '.claude', 'settings.json');
+  const configPath = path.join(HOME_DIR, '.plexor', 'config.json');
 
   try {
     if (!fs.existsSync(settingsPath)) return;
 
     const settings = JSON.parse(fs.readFileSync(settingsPath, 'utf8'));
     const env = settings.env || {};
+    let settingsChanged = false;
 
-    const hasPlexorUrl = env.ANTHROPIC_BASE_URL &&
-                         env.ANTHROPIC_BASE_URL.includes('plexor');
+    const hasPlexorUrl = isManagedGatewayUrl(env.ANTHROPIC_BASE_URL);
 
     if (hasPlexorUrl) {
+      // Fix #2174: Only migrate ANTHROPIC_API_KEY → ANTHROPIC_AUTH_TOKEN
+      // when routing through a Plexor-managed URL. Non-Plexor setups
+      // (direct Anthropic, etc.) should not have their auth mutated.
+      if (env.ANTHROPIC_API_KEY && !env.ANTHROPIC_AUTH_TOKEN) {
+        env.ANTHROPIC_AUTH_TOKEN = env.ANTHROPIC_API_KEY;
+        delete env.ANTHROPIC_API_KEY;
+        settings.env = env;
+        settingsChanged = true;
+        console.log('\n  Migrated ANTHROPIC_API_KEY → ANTHROPIC_AUTH_TOKEN (fix #2174)');
+      } else if (env.ANTHROPIC_API_KEY && env.ANTHROPIC_AUTH_TOKEN) {
+        // Both exist — remove the lower-precedence one to avoid confusion
+        delete env.ANTHROPIC_API_KEY;
+        settings.env = env;
+        settingsChanged = true;
+        console.log('\n  Removed redundant ANTHROPIC_API_KEY (ANTHROPIC_AUTH_TOKEN takes precedence)');
+      }
       // Check if there's a valid Plexor config
       let hasValidConfig = false;
       try {
         if (fs.existsSync(configPath)) {
           const config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
-          hasValidConfig = config.apiKey && config.apiKey.startsWith('plx_');
+          hasValidConfig = (config.auth?.api_key || config.apiKey || '').startsWith('plx_');
         }
       } catch (e) {}
 
@@ -113,10 +218,31 @@ function checkOrphanedRouting() {
         console.log('  Run /plexor-login to reconfigure, or');
         console.log('  Run /plexor-uninstall to clean up\n');
       } else {
-        console.log('\n  Existing Plexor configuration detected');
-        console.log('  Your previous settings have been preserved.\n');
+        // Fix #2176: Detect variant mismatch and migrate URL
+        const currentUrl = env.ANTHROPIC_BASE_URL;
+        if (currentUrl !== THIS_VARIANT_URL) {
+          env.ANTHROPIC_BASE_URL = THIS_VARIANT_URL;
+          settings.env = env;
+          settingsChanged = true;
+          console.log(`\n  Migrated ANTHROPIC_BASE_URL to this variant's gateway:`);
+          console.log(`    Old: ${currentUrl}`);
+          console.log(`    New: ${THIS_VARIANT_URL}\n`);
+        } else {
+          console.log('\n  Existing Plexor configuration detected');
+          console.log('  Your previous settings have been preserved.\n');
+        }
       }
     }
+
+    // Write back settings if any migration was applied
+    if (settingsChanged) {
+      const crypto = require('crypto');
+      const claudeDir = path.join(HOME_DIR, '.claude');
+      const tempId = crypto.randomBytes(8).toString('hex');
+      const tempPath = path.join(claudeDir, `.settings.${tempId}.tmp`);
+      fs.writeFileSync(tempPath, JSON.stringify(settings, null, 2), { mode: 0o600 });
+      fs.renameSync(tempPath, settingsPath);
+    }
   } catch (e) {
     // Ignore errors in detection - don't break install
   }
@@ -295,13 +421,13 @@ function main() {
     console.log('');
     console.log('  For Claude MAX users (OAuth):');
     console.log('');
-    console.log(`    echo 'export ANTHROPIC_BASE_URL="https://api.plexor.dev/gateway/anthropic"' >> ${shellRc}`);
+    console.log(`    echo 'export ANTHROPIC_BASE_URL="https://staging.api.plexor.dev/gateway/anthropic"' >> ${shellRc}`);
     console.log(`    source ${shellRc}`);
     console.log('');
     console.log('  For API key users (get key at https://plexor.dev/dashboard):');
     console.log('');
-    console.log(`    echo 'export ANTHROPIC_BASE_URL="https://api.plexor.dev/gateway/anthropic"' >> ${shellRc}`);
-    console.log(`    echo 'export ANTHROPIC_API_KEY="plx_your_key_here"' >> ${shellRc}`);
+    console.log(`    echo 'export ANTHROPIC_BASE_URL="https://staging.api.plexor.dev/gateway/anthropic"' >> ${shellRc}`);
+    console.log(`    echo 'export ANTHROPIC_AUTH_TOKEN="plx_your_key_here"' >> ${shellRc}`);
     console.log(`    source ${shellRc}`);
     console.log('');
     console.log('  ┌─────────────────────────────────────────────────────────────────┐');

package/scripts/uninstall.js

@@ -15,11 +15,34 @@
 
 const fs = require('fs');
 const path = require('path');
+const os = require('os');
+const { execSync } = require('child_process');
 
-// Get home directory - support both Unix and Windows
-const home = process.env.HOME || process.env.USERPROFILE;
+/**
+ * Get the correct home directory for the process's effective user.
+ * Resolves via /etc/passwd to handle sudo and sudo -u correctly.
+ */
+function getHomeDir() {
+  if (os.platform() !== 'win32') {
+    try {
+      const uid = process.getuid();
+      const entry = execSync(`getent passwd ${uid}`, { encoding: 'utf8' }).trim();
+      const fields = entry.split(':');
+      if (fields.length >= 6 && fields[5]) {
+        return fields[5];
+      }
+    } catch {
+      // Fall through
+    }
+  }
+  const h = os.homedir();
+  if (h) return h;
+  return process.env.HOME || process.env.USERPROFILE || null;
+}
+
+const home = getHomeDir();
 if (!home) {
-  console.log('Warning: HOME not set, skipping cleanup');
+  console.log('Warning: Could not determine home directory, skipping cleanup');
   process.exit(0);
 }