@plexor-dev/claude-code-plugin-staging 0.1.0-beta.25 → 0.1.0-beta.27

package/commands/plexor-logout.js

@@ -115,9 +115,9 @@ function main() {
     process.exit(1);
   }
 
-  // CRITICAL FIX: Disable Claude Code routing in ~/.claude/settings.json
-  // This removes ANTHROPIC_BASE_URL and ANTHROPIC_AUTH_TOKEN so Claude Code
-  // no longer tries to route through Plexor with removed credentials
+  // Disable Claude Code routing in ~/.claude/settings.json.
+  // This removes the Plexor gateway URL and managed Plexor headers so Claude
+  // no longer routes through Plexor with removed credentials.
   const routingDisabled = settingsManager.disablePlexorRouting();
 
   // Clear session

package/commands/plexor-setup.js

@@ -93,7 +93,7 @@ function getGatewayLabel(apiUrl) {
 }
 
 function isRunningInsideClaudeSession(env = process.env) {
-  return Boolean(env.CLAUDECODE);
+  return Boolean(env.CLAUDECODE || env.PLEXOR_SETUP_IN_CLAUDE);
 }
 
 function createSkipVerifyResult() {
@@ -143,6 +143,14 @@ function printUsage() {
   console.log('  PLEXOR_API_KEY=plx_... /plexor-setup');
 }
 
+function printRestartBanner() {
+  const BRIGHT_YELLOW = '\x1b[93m';
+  const BOLD = '\x1b[1m';
+  const RESET = '\x1b[0m';
+  console.log('');
+  console.log(`${BOLD}${BRIGHT_YELLOW}RESTART CLAUDE NOW.${RESET}`);
+}
+
 function printReceipt({ user, gateway, previousAuthPreserved, verifyResult }) {
   const line = (content) => `│  ${String(content).slice(0, 43).padEnd(43)}│`;
 
@@ -169,7 +177,11 @@ function printReceipt({ user, gateway, previousAuthPreserved, verifyResult }) {
   }
   console.log('└─────────────────────────────────────────────┘');
 
-  if (!verifyResult.ok) {
+  if (verifyResult.pendingRestart) {
+    printRestartBanner();
+  }
+
+  if (!verifyResult.ok && !verifyResult.pendingRestart) {
     console.log('');
     console.log(`Verification failed: ${verifyResult.reason}`);
   }

package/commands/plexor-setup.md

@@ -1,14 +1,14 @@
 description: Guided first-run setup for Plexor with Claude Code (user)
 ---
 
-**RULE: Execute this workflow EXACTLY ONCE. After the Bash tool returns output, your ONLY action is to present that output to the user. DO NOT restart the workflow.**
+**RULE: Execute this workflow EXACTLY ONCE. After the Bash tool returns output, your ONLY action is to present that output to the user. If the output says restart is required, add one standalone line exactly `RESTART CLAUDE NOW.` after the tool output. DO NOT restart the workflow.**
 
 Plexor setup is the primary human setup flow.
 
 If `$ARGUMENTS` already contains a Plexor API key (`plx_...`), run:
 
 ```bash
-node ~/.claude/plugins/plexor/commands/plexor-setup.js $ARGUMENTS
+PLEXOR_SETUP_IN_CLAUDE=1 node ~/.claude/plugins/plexor/commands/plexor-setup.js $ARGUMENTS
 ```
 
 If the user did not provide a key yet, ask them:
@@ -18,11 +18,11 @@ If the user did not provide a key yet, ask them:
 After the user replies with the key, run:
 
 ```bash
-node ~/.claude/plugins/plexor/commands/plexor-setup.js <user_key>
+PLEXOR_SETUP_IN_CLAUDE=1 node ~/.claude/plugins/plexor/commands/plexor-setup.js <user_key>
 ```
 
 This command:
 - saves the Plexor key
 - routes Claude through the Plexor staging gateway
-- preserves prior direct Claude auth for restore on logout/uninstall
+- keeps Claude's existing direct auth intact and adds Plexor auth via managed headers
 - runs a deterministic Claude verification step

package/commands/plexor-status.js

@@ -8,6 +8,7 @@
 const fs = require('fs');
 const path = require('path');
 const https = require('https');
+const { parseCustomHeaders } = require('../lib/config-utils');
 
 // Import centralized constants with HOME directory validation
 const { HOME_DIR, CONFIG_PATH, SESSION_PATH, SESSION_TIMEOUT_MS } = require('../lib/constants');
@@ -26,12 +27,15 @@ function isManagedGatewayUrl(baseUrl = '') {
 }
 
 function getPlexorAuthKey(env = {}) {
+  const headers = parseCustomHeaders(env.ANTHROPIC_CUSTOM_HEADERS);
+  const headerApiKey = headers['x-plexor-key'] || '';
   const apiKey = env.ANTHROPIC_API_KEY || '';
   const authToken = env.ANTHROPIC_AUTH_TOKEN || '';
 
+  if (headerApiKey.startsWith('plx_')) return headerApiKey;
   if (apiKey.startsWith('plx_')) return apiKey;
   if (authToken.startsWith('plx_')) return authToken;
-  return apiKey || authToken || '';
+  return '';
 }
 
 function getDirectClaudeAuthState() {

package/commands/plexor-uninstall.js

@@ -18,18 +18,24 @@
 const fs = require('fs');
 const path = require('path');
 const os = require('os');
+const { execSync } = require('child_process');
 const { removeManagedStatusLine } = require('../lib/statusline-manager');
 const { removeManagedHooks, cleanupLegacyManagedHooksFile } = require('../lib/hooks-manager');
 const { removeManagedClaudeCustomHeadersFromEnv } = require('../lib/config-utils');
 
 // Get home directory, handling sudo case
 function getHomeDir() {
-  if (process.env.SUDO_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);
+  if (os.platform() !== 'win32' && process.env.SUDO_USER) {
+    try {
+      if (typeof process.getuid === 'function' && process.getuid() === 0) {
+        const entry = execSync(`getent passwd ${process.env.SUDO_USER}`, { encoding: 'utf8' }).trim();
+        const fields = entry.split(':');
+        if (fields.length >= 6 && fields[5]) {
+          return fields[5];
+        }
+      }
+    } catch {
+      // Fall through to HOME/os.homedir below.
     }
   }
   return process.env.HOME || process.env.USERPROFILE || os.homedir();

package/lib/config-utils.js

@@ -12,6 +12,7 @@ const DISABLED_HINT_VALUES = new Set(['', 'auto', 'none', 'off']);
 const VALID_ORCHESTRATION_MODES = new Set(['supervised', 'autonomous', 'danger-full-auto']);
 const VALID_ROUTING_MODES = new Set(['eco', 'balanced', 'quality', 'passthrough', 'cost']);
 const MANAGED_HEADER_KEYS = new Set([
+  'x-plexor-key',
   'x-force-provider',
   'x-force-model',
   'x-allow-providers',
@@ -23,6 +24,10 @@ const MANAGED_HEADER_KEYS = new Set([
 ]);
 const CLAUDE_SETTINGS_PATH = path.join(os.homedir(), '.claude', 'settings.json');
 
+function isPlexorApiKey(value = '') {
+  return typeof value === 'string' && value.startsWith('plx_');
+}
+
 function normalizeForcedProvider(value) {
   if (typeof value !== 'string') {
     return null;
@@ -137,9 +142,39 @@ function removeManagedClaudeCustomHeadersFromEnv(env = {}) {
   return true;
 }
 
+function getManagedPlexorAuthHeader(env = {}) {
+  const existing = parseCustomHeaders(env.ANTHROPIC_CUSTOM_HEADERS);
+  const managedAuthKey = existing['x-plexor-key'] || '';
+  return isPlexorApiKey(managedAuthKey) ? managedAuthKey : '';
+}
+
+function upsertManagedPlexorAuthHeader(env = {}, apiKey = '') {
+  const existing = parseCustomHeaders(env.ANTHROPIC_CUSTOM_HEADERS);
+  const previousHeaders = env.ANTHROPIC_CUSTOM_HEADERS || '';
+
+  if (isPlexorApiKey(apiKey)) {
+    existing['x-plexor-key'] = apiKey;
+  } else {
+    delete existing['x-plexor-key'];
+  }
+
+  if (Object.keys(existing).length) {
+    env.ANTHROPIC_CUSTOM_HEADERS = serializeCustomHeaders(existing);
+  } else {
+    delete env.ANTHROPIC_CUSTOM_HEADERS;
+  }
+
+  return (env.ANTHROPIC_CUSTOM_HEADERS || '') !== previousHeaders;
+}
+
 function buildManagedAnthropicHeaders(config) {
   const settings = config?.settings || {};
   const headers = {};
+  const apiKey = config?.auth?.api_key || config?.auth?.apiKey || config?.apiKey || '';
+
+  if (isPlexorApiKey(apiKey)) {
+    headers['x-plexor-key'] = apiKey;
+  }
 
   const modeRaw = String(settings.mode || '')
     .trim()
@@ -194,6 +229,25 @@ function buildManagedAnthropicHeaders(config) {
   return headers;
 }
 
+function applyManagedClaudeCustomHeadersToEnv(env = {}, config = {}) {
+  const previousHeaders = env.ANTHROPIC_CUSTOM_HEADERS || '';
+  const existing = parseCustomHeaders(env.ANTHROPIC_CUSTOM_HEADERS);
+  for (const key of MANAGED_HEADER_KEYS) {
+    delete existing[key];
+  }
+
+  const managed = buildManagedAnthropicHeaders(config);
+  const merged = { ...existing, ...managed };
+
+  if (Object.keys(merged).length) {
+    env.ANTHROPIC_CUSTOM_HEADERS = serializeCustomHeaders(merged);
+  } else {
+    delete env.ANTHROPIC_CUSTOM_HEADERS;
+  }
+
+  return (env.ANTHROPIC_CUSTOM_HEADERS || '') !== previousHeaders;
+}
+
 function syncClaudeCustomHeaders(config) {
   try {
     let settings = {};
@@ -207,19 +261,7 @@ function syncClaudeCustomHeaders(config) {
     }
     settings.env = settings.env && typeof settings.env === 'object' ? settings.env : {};
 
-    const existing = parseCustomHeaders(settings.env.ANTHROPIC_CUSTOM_HEADERS);
-    for (const key of MANAGED_HEADER_KEYS) {
-      delete existing[key];
-    }
-
-    const managed = buildManagedAnthropicHeaders(config);
-    const merged = { ...existing, ...managed };
-
-    if (Object.keys(merged).length) {
-      settings.env.ANTHROPIC_CUSTOM_HEADERS = serializeCustomHeaders(merged);
-    } else {
-      delete settings.env.ANTHROPIC_CUSTOM_HEADERS;
-    }
+    applyManagedClaudeCustomHeadersToEnv(settings.env, config);
 
     const claudeDir = path.dirname(CLAUDE_SETTINGS_PATH);
     if (!fs.existsSync(claudeDir)) {
@@ -332,6 +374,9 @@ module.exports = {
   readSetting,
   hasForcedHintConflict,
   validateForcedHintConfig,
+  applyManagedClaudeCustomHeadersToEnv,
+  getManagedPlexorAuthHeader,
+  upsertManagedPlexorAuthHeader,
   removeManagedClaudeCustomHeadersFromEnv,
   parseCustomHeaders,
   serializeCustomHeaders,

package/lib/settings-manager.js

@@ -14,12 +14,15 @@ const fs = require('fs');
 const path = require('path');
 const os = require('os');
 const crypto = require('crypto');
-const { removeManagedClaudeCustomHeadersFromEnv } = require('./config-utils');
+const {
+  getManagedPlexorAuthHeader,
+  removeManagedClaudeCustomHeadersFromEnv,
+  upsertManagedPlexorAuthHeader
+} = require('./config-utils');
 
 const CLAUDE_DIR = path.join(process.env.HOME || process.env.USERPROFILE || '', '.claude');
 const CLAUDE_STATE_PATH = path.join(process.env.HOME || process.env.USERPROFILE || '', '.claude.json');
 const SETTINGS_PATH = path.join(CLAUDE_DIR, 'settings.json');
-const LOCK_TIMEOUT_MS = 5000; // 5 second lock timeout
 
 // Plexor gateway endpoints
 const PLEXOR_STAGING_URL = 'https://staging.api.plexor.dev/gateway/anthropic';
@@ -49,44 +52,47 @@ function isPlexorApiKey(value = '') {
 }
 
 function getPlexorAuthKey(env = {}) {
+  const headerKey = getManagedPlexorAuthHeader(env);
   const apiKey = env.ANTHROPIC_API_KEY || '';
   const authToken = env.ANTHROPIC_AUTH_TOKEN || '';
 
+  if (isPlexorApiKey(headerKey)) return headerKey;
   if (isPlexorApiKey(apiKey)) return apiKey;
   if (isPlexorApiKey(authToken)) return authToken;
-  return apiKey || authToken || '';
+  return '';
 }
 
-function hasPlexorManagedAuth(env = {}) {
-  return (
-    isManagedGatewayUrl(env.ANTHROPIC_BASE_URL || '') ||
-    isPlexorApiKey(env.ANTHROPIC_API_KEY || '') ||
-    isPlexorApiKey(env.ANTHROPIC_AUTH_TOKEN || '')
-  );
-}
-
-function stashDirectAuthEnv(env, plexorApiKey) {
-  const alreadyManaged = hasPlexorManagedAuth(env);
-  const currentApiKey = env.ANTHROPIC_API_KEY || '';
-  const currentAuthToken = env.ANTHROPIC_AUTH_TOKEN || '';
+function clearLegacyPlexorAuthValue(env = {}, field, backupField) {
+  let changed = false;
+  const currentValue = env[field] || '';
+  const backupValue = env[backupField] || '';
 
-  if (currentApiKey && !isPlexorApiKey(currentApiKey) && currentApiKey !== plexorApiKey) {
-    env[PREVIOUS_API_KEY_ENV] = currentApiKey;
-  } else if (!alreadyManaged) {
-    delete env[PREVIOUS_API_KEY_ENV];
+  if (isPlexorApiKey(currentValue)) {
+    if (backupValue && !isPlexorApiKey(backupValue)) {
+      env[field] = backupValue;
+    } else {
+      delete env[field];
+    }
+    changed = true;
   }
 
-  if (currentAuthToken && !isPlexorApiKey(currentAuthToken) && currentAuthToken !== plexorApiKey) {
-    env[PREVIOUS_AUTH_TOKEN_ENV] = currentAuthToken;
-  } else if (!alreadyManaged) {
-    delete env[PREVIOUS_AUTH_TOKEN_ENV];
+  if (backupValue) {
+    delete env[backupField];
+    changed = true;
   }
+
+  return changed;
 }
 
-function setPlexorAuthKey(env, apiKey) {
-  stashDirectAuthEnv(env, apiKey);
-  env.ANTHROPIC_API_KEY = apiKey;
-  env.ANTHROPIC_AUTH_TOKEN = apiKey;
+function migrateLegacyPlexorAuthEnv(env = {}, claudeState = {}) {
+  let changed = false;
+
+  changed = clearLegacyPlexorAuthValue(env, 'ANTHROPIC_API_KEY', PREVIOUS_API_KEY_ENV) || changed;
+  changed = clearLegacyPlexorAuthValue(env, 'ANTHROPIC_AUTH_TOKEN', PREVIOUS_AUTH_TOKEN_ENV) || changed;
+
+  changed = restoreDirectPrimaryApiKey(env, claudeState) || changed;
+
+  return changed;
 }
 
 function clearPlexorRoutingEnv(env = {}) {
@@ -122,17 +128,6 @@ function clearPlexorRoutingEnv(env = {}) {
   return true;
 }
 
-function stashDirectPrimaryApiKey(env = {}, claudeState = {}, plexorApiKey = '') {
-  const currentPrimaryApiKey = claudeState.primaryApiKey || '';
-  if (!currentPrimaryApiKey || isPlexorApiKey(currentPrimaryApiKey) || currentPrimaryApiKey === plexorApiKey) {
-    return false;
-  }
-
-  env[PREVIOUS_PRIMARY_API_KEY_ENV] = currentPrimaryApiKey;
-  delete claudeState.primaryApiKey;
-  return true;
-}
-
 function restoreDirectPrimaryApiKey(env = {}, claudeState = {}, options = {}) {
   const { consumeBackup = true } = options;
   const previousPrimaryApiKey = env[PREVIOUS_PRIMARY_API_KEY_ENV] || '';
@@ -356,11 +351,9 @@ class ClaudeSettingsManager {
         settings.env = {};
       }
 
-      // Mirror the Plexor key into both Claude auth env vars so every Claude
-      // runtime path uses the gateway instead of any previously saved direct key.
       settings.env.ANTHROPIC_BASE_URL = apiUrl;
-      setPlexorAuthKey(settings.env, apiKey);
-      const claudeStateChanged = stashDirectPrimaryApiKey(settings.env, claudeState, apiKey);
+      upsertManagedPlexorAuthHeader(settings.env, apiKey);
+      const claudeStateChanged = migrateLegacyPlexorAuthEnv(settings.env, claudeState);
 
       const success = this.save(settings);
       if (!success) {
@@ -493,9 +486,6 @@ class ClaudeSettingsManager {
       if (isPlexorUrl && !isPlexorApiKey(authKey)) {
         return { partial: true, issue: 'Plexor URL set but auth key is not a Plexor key' };
       }
-      if (isPlexorUrl && claudeState.primaryApiKey && !isPlexorApiKey(claudeState.primaryApiKey)) {
-        return { partial: true, issue: 'Plexor URL set but Claude managed API key is still active' };
-      }
       return { partial: false, issue: null };
     } catch {
       return { partial: false, issue: null };
@@ -515,8 +505,19 @@ class ClaudeSettingsManager {
         settings.env = {};
       }
 
-      setPlexorAuthKey(settings.env, apiKey);
-      return this.save(settings);
+      const previousSettings = JSON.parse(JSON.stringify(settings));
+      const claudeState = this.loadClaudeState();
+      upsertManagedPlexorAuthHeader(settings.env, apiKey);
+      const claudeStateChanged = migrateLegacyPlexorAuthEnv(settings.env, claudeState);
+      const success = this.save(settings);
+      if (!success) {
+        return false;
+      }
+      if (claudeStateChanged && !this.saveClaudeState(claudeState)) {
+        this.save(previousSettings);
+        return false;
+      }
+      return true;
     } catch (err) {
       console.error('Failed to update API key:', err.message);
       return false;

package/lib/supervisor.js

@@ -0,0 +1,282 @@
+/**
+ * Plexor Supervisor Emitter — Phases 1-4
+ *
+ * Phase 1: Basic routing summary
+ *   [PLEXOR: Routed to {provider}/{model}, {latency}ms, {routing_source}]
+ *
+ * Phase 2: Enhanced routing with cohort from response body fields
+ *   [PLEXOR: {provider}/{model}, {latency}ms, {source} | {cohort}]
+ *
+ * Phase 3: Zero-tool escalation detection (agent_halt / escalation signals)
+ *   [PLEXOR: Zero-tool escalation: {provider1} → {provider2}]
+ *
+ * Phase 4: Scaffolding gate blocked detection
+ *   [PLEXOR: Scaffolding gate: {model} blocked, using {alternative}]
+ *
+ * This module is consumed by track-response.js to surface routing
+ * decisions to the developer without requiring them to parse verbose logs.
+ */
+
+const CYAN = '\x1b[36m';
+const YELLOW = '\x1b[33m';
+const RED = '\x1b[31m';
+const RESET = '\x1b[0m';
+
+class SupervisorEmitter {
+  /**
+   * @param {object} [opts]
+   * @param {boolean} [opts.enabled] — honour PLEXOR_SUPERVISOR env var (default true)
+   */
+  constructor(opts = {}) {
+    const envFlag = process.env.PLEXOR_SUPERVISOR;
+    if (envFlag !== undefined) {
+      this.enabled = !/^(0|false|no|off)$/i.test(String(envFlag));
+    } else {
+      this.enabled = opts.enabled !== false;
+    }
+  }
+
+  /**
+   * Build the Phase 2 enhanced supervisor summary from a gateway response.
+   * Reads plexor_provider_used, plexor_selected_model, plexor_latency_ms,
+   * plexor_routing_source from the response body (not just headers).
+   *
+   * Format: [PLEXOR: provider/model, latencyms, source | cohort]
+   *
+   * @param {object} response  — the full LLM response object
+   * @param {object} [plexorMeta] — the _plexor metadata block (may be absent)
+   * @returns {string|null}
+   */
+  buildSummary(response, plexorMeta) {
+    if (!response || typeof response !== 'object') {
+      return null;
+    }
+
+    const provider = this._resolveProvider(response, plexorMeta);
+    const model = this._resolveModel(response, plexorMeta);
+    const latencyMs = this._resolveLatency(response, plexorMeta);
+    const routingSource = this._resolveRoutingSource(response, plexorMeta);
+    const cohort = this._resolveCohort(response, plexorMeta);
+
+    // Need at least provider or model to emit anything useful
+    if (!provider && !model) {
+      return null;
+    }
+
+    const target = [provider, model].filter(Boolean).join('/');
+    const parts = [target];
+
+    if (latencyMs !== null) {
+      parts.push(`${latencyMs}ms`);
+    }
+
+    if (routingSource) {
+      parts.push(routingSource);
+    }
+
+    let line = parts.join(', ');
+
+    if (cohort) {
+      line += ` | ${cohort}`;
+    }
+
+    return `[PLEXOR: ${line}]`;
+  }
+
+  /**
+   * Phase 3: Detect zero-tool escalation signals in the response.
+   * Fires when agent_halt is set or escalation_chain / fallback provider data
+   * indicates a provider switch due to tool incapability.
+   *
+   * @param {object} response
+   * @param {object} [plexorMeta]
+   * @returns {string|null} — escalation message or null
+   */
+  buildEscalationNotice(response, plexorMeta) {
+    if (!response || typeof response !== 'object') {
+      return null;
+    }
+
+    const agentHalt = this._toBool(
+      response?.plexor_agent_halt ??
+      response?.plexor?.agent_halt ??
+      plexorMeta?.agent_halt
+    );
+
+    const escalationChain =
+      response?.plexor_escalation_chain ||
+      response?.plexor?.escalation_chain ||
+      plexorMeta?.escalation_chain ||
+      null;
+
+    const fallbackUsed = this._toBool(
+      response?.plexor_fallback_used ??
+      response?.fallback_used ??
+      response?.plexor?.fallback_used
+    );
+
+    const originalProvider =
+      response?.plexor_original_provider ||
+      response?.plexor?.original_provider ||
+      plexorMeta?.original_provider ||
+      null;
+
+    const currentProvider = this._resolveProvider(response, plexorMeta);
+
+    // Case 1: Explicit escalation chain present (e.g., ["openai-mini", "openai"])
+    if (Array.isArray(escalationChain) && escalationChain.length >= 2) {
+      const from = escalationChain[0];
+      const to = escalationChain[escalationChain.length - 1];
+      return `[PLEXOR: Zero-tool escalation: ${from} \u2192 ${to}]`;
+    }
+
+    // Case 2: agent_halt with fallback — provider switched
+    if (agentHalt && fallbackUsed && originalProvider && currentProvider && originalProvider !== currentProvider) {
+      return `[PLEXOR: Zero-tool escalation: ${originalProvider} \u2192 ${currentProvider}]`;
+    }
+
+    // Case 3: agent_halt alone (escalation happened but we may not know the full chain)
+    if (agentHalt && fallbackUsed) {
+      const from = originalProvider || 'original';
+      const to = currentProvider || 'fallback';
+      return `[PLEXOR: Zero-tool escalation: ${from} \u2192 ${to}]`;
+    }
+
+    return null;
+  }
+
+  /**
+   * Phase 4: Detect scaffolding gate blocks.
+   * Fires when scaffolding_gate_blocked is present in the response,
+   * indicating a model was blocked by the scaffolding gate and an
+   * alternative was used.
+   *
+   * @param {object} response
+   * @param {object} [plexorMeta]
+   * @returns {string|null}
+   */
+  buildScaffoldingGateNotice(response, plexorMeta) {
+    if (!response || typeof response !== 'object') {
+      return null;
+    }
+
+    const gateBlocked = this._toBool(
+      response?.plexor_scaffolding_gate_blocked ??
+      response?.scaffolding_gate_blocked ??
+      response?.plexor?.scaffolding_gate_blocked ??
+      plexorMeta?.scaffolding_gate_blocked
+    );
+
+    if (!gateBlocked) {
+      return null;
+    }
+
+    const blockedModel =
+      response?.plexor_scaffolding_blocked_model ||
+      response?.plexor?.scaffolding_blocked_model ||
+      plexorMeta?.scaffolding_blocked_model ||
+      response?.plexor_original_model ||
+      response?.plexor?.original_model ||
+      plexorMeta?.original_model ||
+      'model';
+
+    const alternative =
+      response?.plexor_selected_model ||
+      response?.plexor?.selected_model ||
+      plexorMeta?.recommended_model ||
+      response?.model ||
+      'alternative';
+
+    return `[PLEXOR: Scaffolding gate: ${blockedModel} blocked, using ${alternative}]`;
+  }
+
+  /**
+   * Emit all applicable supervisor lines to stderr if enabled.
+   *
+   * @param {object} response
+   * @param {object} [plexorMeta]
+   */
+  emit(response, plexorMeta) {
+    if (!this.enabled) {
+      return;
+    }
+
+    // Phase 4: Scaffolding gate (highest priority — emit first if present)
+    const scaffoldingNotice = this.buildScaffoldingGateNotice(response, plexorMeta);
+    if (scaffoldingNotice) {
+      process.stderr.write(`${RED}${scaffoldingNotice}${RESET}\n`);
+    }
+
+    // Phase 3: Escalation notice
+    const escalationNotice = this.buildEscalationNotice(response, plexorMeta);
+    if (escalationNotice) {
+      process.stderr.write(`${YELLOW}${escalationNotice}${RESET}\n`);
+    }
+
+    // Phase 2: Enhanced routing summary (always emitted when data available)
+    const summary = this.buildSummary(response, plexorMeta);
+    if (summary) {
+      process.stderr.write(`${CYAN}${summary}${RESET}\n`);
+    }
+  }
+
+  // ---- private helpers ----
+
+  _resolveProvider(response, meta) {
+    return (
+      response?.plexor_provider_used ||
+      response?.plexor?.provider_used ||
+      meta?.recommended_provider ||
+      null
+    );
+  }
+
+  _resolveModel(response, meta) {
+    return (
+      response?.plexor_selected_model ||
+      response?.plexor?.selected_model ||
+      meta?.recommended_model ||
+      response?.model ||
+      null
+    );
+  }
+
+  _resolveLatency(response, meta) {
+    const raw =
+      response?.plexor_latency_ms ??
+      response?.plexor?.latency_ms ??
+      meta?.latency_ms ??
+      null;
+    if (raw === null || raw === undefined) {
+      return null;
+    }
+    const n = Number(raw);
+    return Number.isFinite(n) ? Math.round(n) : null;
+  }
+
+  _resolveRoutingSource(response, meta) {
+    return (
+      response?.plexor_routing_source ||
+      response?.plexor?.routing_source ||
+      meta?.source ||
+      null
+    );
+  }
+
+  _resolveCohort(response, meta) {
+    return (
+      response?.plexor_cohort ||
+      response?.plexor?.cohort ||
+      meta?.cohort ||
+      null
+    );
+  }
+
+  _toBool(value) {
+    if (value === true || value === 'true' || value === '1' || value === 1) return true;
+    if (value === false || value === 'false' || value === '0' || value === 0) return false;
+    return null;
+  }
+}
+
+module.exports = { SupervisorEmitter };

package/package.json

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

package/scripts/plexor-cli.sh

@@ -21,7 +21,12 @@ if [ -f "$CONFIG_FILE" ]; then
     if [ "$ENABLED" = "True" ] && [ -n "$API_URL" ] && [ -n "$API_KEY" ]; then
         # Set ANTHROPIC_BASE_URL to Plexor gateway (hypervisor mode)
         export ANTHROPIC_BASE_URL="${API_URL}/gateway/anthropic/v1"
-        export ANTHROPIC_API_KEY="$API_KEY"
+        if [ -n "$ANTHROPIC_CUSTOM_HEADERS" ]; then
+            export ANTHROPIC_CUSTOM_HEADERS="x-plexor-key: ${API_KEY}
+${ANTHROPIC_CUSTOM_HEADERS}"
+        else
+            export ANTHROPIC_CUSTOM_HEADERS="x-plexor-key: ${API_KEY}"
+        fi
 
         # Show Plexor branding
         echo -e "${CYAN}"

package/scripts/postinstall.js

@@ -11,6 +11,10 @@ const fs = require('fs');
 const path = require('path');
 const os = require('os');
 const { execSync } = require('child_process');
+const {
+  applyManagedClaudeCustomHeadersToEnv,
+  getManagedPlexorAuthHeader
+} = require('../lib/config-utils');
 const { upsertManagedStatusLine } = require('../lib/statusline-manager');
 const { upsertManagedHooks, cleanupLegacyManagedHooksFile } = require('../lib/hooks-manager');
 
@@ -178,31 +182,42 @@ const PREVIOUS_PRIMARY_API_KEY_ENV = 'PLEXOR_PREVIOUS_CLAUDE_PRIMARY_API_KEY';
 /**
  * Check for orphaned Plexor routing in settings.json without valid config.
  * Also detects variant mismatch (e.g., localhost plugin was installed, now
- * installing staging plugin) and migrates ANTHROPIC_BASE_URL + syncs
- * Claude auth env vars for Plexor-managed gateways.
+ * installing staging plugin) and migrates legacy env-based Plexor auth into
+ * managed Claude custom headers.
  */
-function selectManagedAuthKey(env = {}) {
+function selectManagedAuthKey(env = {}, config = {}) {
+  const configApiKey = config.auth?.api_key || config.auth?.apiKey || config.apiKey || '';
   const apiKey = env.ANTHROPIC_API_KEY || '';
   const authToken = env.ANTHROPIC_AUTH_TOKEN || '';
+  const headerApiKey = getManagedPlexorAuthHeader(env);
 
+  if (configApiKey.startsWith('plx_')) return configApiKey;
+  if (headerApiKey.startsWith('plx_')) return headerApiKey;
   if (apiKey.startsWith('plx_')) return apiKey;
   if (authToken.startsWith('plx_')) return authToken;
-  return apiKey || authToken || '';
+  return '';
 }
 
-function syncManagedAuthEnv(env, managedAuthKey) {
-  const currentApiKey = env.ANTHROPIC_API_KEY || '';
-  const currentAuthToken = env.ANTHROPIC_AUTH_TOKEN || '';
+function restoreLegacyManagedAuthEnvValue(env, field, backupField) {
+  let changed = false;
+  const currentValue = env[field] || '';
+  const backupValue = env[backupField] || '';
 
-  if (currentApiKey && !currentApiKey.startsWith('plx_') && currentApiKey !== managedAuthKey) {
-    env[PREVIOUS_API_KEY_ENV] = currentApiKey;
+  if (currentValue.startsWith('plx_')) {
+    if (backupValue && !backupValue.startsWith('plx_')) {
+      env[field] = backupValue;
+    } else {
+      delete env[field];
+    }
+    changed = true;
   }
-  if (currentAuthToken && !currentAuthToken.startsWith('plx_') && currentAuthToken !== managedAuthKey) {
-    env[PREVIOUS_AUTH_TOKEN_ENV] = currentAuthToken;
+
+  if (backupValue) {
+    delete env[backupField];
+    changed = true;
   }
 
-  env.ANTHROPIC_API_KEY = managedAuthKey;
-  env.ANTHROPIC_AUTH_TOKEN = managedAuthKey;
+  return changed;
 }
 
 function writeJsonAtomically(filePath, value) {
@@ -211,36 +226,36 @@ function writeJsonAtomically(filePath, value) {
   fs.renameSync(tempPath, filePath);
 }
 
-function syncManagedPrimaryApiKey(env, managedAuthKey) {
-  const statePath = path.join(HOME_DIR, '.claude.json');
-  try {
-    if (!fs.existsSync(statePath)) {
-      return { changed: false };
-    }
+function migrateManagedAuthState(env, claudeState, config = {}) {
+  let settingsChanged = false;
+  let claudeStateChanged = false;
+  const managedAuthKey = selectManagedAuthKey(env, config);
+
+  if (managedAuthKey) {
+    const managedConfig = {
+      ...config,
+      auth: {
+        ...(config.auth || {}),
+        api_key: managedAuthKey
+      }
+    };
+    settingsChanged = applyManagedClaudeCustomHeadersToEnv(env, managedConfig) || settingsChanged;
+  }
 
-    const data = fs.readFileSync(statePath, 'utf8');
-    if (!data || !data.trim()) {
-      return { changed: false };
-    }
+  settingsChanged = restoreLegacyManagedAuthEnvValue(env, 'ANTHROPIC_API_KEY', PREVIOUS_API_KEY_ENV) || settingsChanged;
+  settingsChanged = restoreLegacyManagedAuthEnvValue(env, 'ANTHROPIC_AUTH_TOKEN', PREVIOUS_AUTH_TOKEN_ENV) || settingsChanged;
 
-    const claudeState = JSON.parse(data);
-    const primaryApiKey = claudeState.primaryApiKey || '';
-    if (!primaryApiKey || primaryApiKey.startsWith('plx_') || primaryApiKey === managedAuthKey) {
-      return { changed: false };
+  const previousPrimaryApiKey = env[PREVIOUS_PRIMARY_API_KEY_ENV] || '';
+  if (previousPrimaryApiKey) {
+    if (!claudeState.primaryApiKey) {
+      claudeState.primaryApiKey = previousPrimaryApiKey;
+      claudeStateChanged = true;
     }
-
-    env[PREVIOUS_PRIMARY_API_KEY_ENV] = primaryApiKey;
-    const nextClaudeState = { ...claudeState };
-    delete nextClaudeState.primaryApiKey;
-
-    return {
-      changed: true,
-      statePath,
-      claudeState: nextClaudeState
-    };
-  } catch {
-    return { changed: false };
+    delete env[PREVIOUS_PRIMARY_API_KEY_ENV];
+    settingsChanged = true;
   }
+
+  return { settingsChanged, claudeStateChanged };
 }
 
 function checkOrphanedRouting() {
@@ -254,32 +269,19 @@ function checkOrphanedRouting() {
     const settings = JSON.parse(fs.readFileSync(settingsPath, 'utf8'));
     const env = settings.env || {};
     let settingsChanged = false;
-    let managedPrimaryApiKeySync = null;
+    let claudeStateChanged = false;
+    let claudeState = {};
+    const statePath = path.join(HOME_DIR, '.claude.json');
 
     const hasPlexorUrl = isManagedGatewayUrl(env.ANTHROPIC_BASE_URL);
 
     if (hasPlexorUrl) {
-      // Keep both Claude auth env vars aligned to the Plexor key so Claude API
-      // auth cannot override the gateway after plugin setup.
-      const managedAuthKey = selectManagedAuthKey(env);
-      if (managedAuthKey &&
-          (env.ANTHROPIC_API_KEY !== managedAuthKey || env.ANTHROPIC_AUTH_TOKEN !== managedAuthKey)) {
-        syncManagedAuthEnv(env, managedAuthKey);
-        settings.env = env;
-        settingsChanged = true;
-        console.log('\n  Synced Plexor auth into ANTHROPIC_API_KEY and ANTHROPIC_AUTH_TOKEN');
-      }
-      const primaryApiKeySync = managedAuthKey ? syncManagedPrimaryApiKey(env, managedAuthKey) : { changed: false };
-      if (primaryApiKeySync.changed) {
-        settings.env = env;
-        settingsChanged = true;
-        managedPrimaryApiKeySync = primaryApiKeySync;
-      }
       // Check if there's a valid Plexor config
       let hasValidConfig = false;
+      let config = null;
       try {
         if (fs.existsSync(configPath)) {
-          const config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+          config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
           hasValidConfig = (config.auth?.api_key || config.apiKey || '').startsWith('plx_');
         }
       } catch (e) {}
@@ -290,6 +292,22 @@ function checkOrphanedRouting() {
         console.log('  Run /plexor-login to reconfigure, or');
         console.log('  Run /plexor-uninstall to clean up\n');
       } else {
+        try {
+          if (fs.existsSync(statePath)) {
+            const data = fs.readFileSync(statePath, 'utf8');
+            if (data && data.trim()) {
+              claudeState = JSON.parse(data);
+            }
+          }
+        } catch {
+          claudeState = {};
+        }
+
+        const migration = migrateManagedAuthState(env, claudeState, config);
+        settings.env = env;
+        settingsChanged = migration.settingsChanged || settingsChanged;
+        claudeStateChanged = migration.claudeStateChanged || claudeStateChanged;
+
         // Fix #2176: Detect variant mismatch and migrate URL
         const currentUrl = env.ANTHROPIC_BASE_URL;
         if (currentUrl !== THIS_VARIANT_URL) {
@@ -316,12 +334,12 @@ function checkOrphanedRouting() {
       fs.renameSync(tempPath, settingsPath);
     }
 
-    if (managedPrimaryApiKeySync?.changed) {
+    if (claudeStateChanged) {
       try {
-        writeJsonAtomically(managedPrimaryApiKeySync.statePath, managedPrimaryApiKeySync.claudeState);
-        console.log('\n  Suspended Claude managed API key while Plexor is active');
+        writeJsonAtomically(statePath, claudeState);
+        console.log('\n  Restored saved Claude auth alongside Plexor header routing');
       } catch (e) {
-        console.log('\n  Warning: Saved Claude key backup but could not suspend Claude managed API key');
+        console.log('\n  Warning: Migrated Plexor auth headers but could not restore saved Claude auth');
         console.log(`  ${e.message}`);
       }
     }

package/scripts/uninstall.js

@@ -59,7 +59,8 @@ const results = {
   hooks: false,
   commands: [],
   restored: [],
-  pluginDir: false
+  pluginDir: false,
+  configDir: false
 };
 const PREVIOUS_PRIMARY_API_KEY_ENV = 'PLEXOR_PREVIOUS_CLAUDE_PRIMARY_API_KEY';
 const CLAUDE_SETTINGS_PATH = path.join(home, '.claude', 'settings.json');
@@ -254,7 +255,14 @@ try {
 }
 
 // Output results
-if (results.routing || results.statusLine || results.hooks || results.commands.length > 0 || results.pluginDir) {
+if (
+  results.routing ||
+  results.statusLine ||
+  results.hooks ||
+  results.commands.length > 0 ||
+  results.pluginDir ||
+  results.configDir
+) {
   console.log('  Plexor plugin uninstalled');
   console.log('');