sneakoscope 0.9.8 → 0.9.10

package/README.md

@@ -210,6 +210,8 @@ Flags:
 
 `sks codex-lb status` reports whether a ChatGPT OAuth backup is present and shows the `sks codex-lb release` hint when applicable. `sks doctor` surfaces the same hint.
 
+If Codex App shows `access token could not be refreshed` after codex-lb setup or status checks, recover the ChatGPT OAuth side without discarding codex-lb: run `sks codex-lb status`, then `sks codex-lb repair`. Repair restores a ChatGPT OAuth backup when one exists while keeping `model_provider = "codex-lb"` selected and the codex-lb key in `CODEX_LB_API_KEY`. If no OAuth backup exists, sign in again in Codex App/CLI, then rerun `sks codex-lb repair`. Use `sks codex-lb release` only when you want to switch fully away from codex-lb.
+
 If you only want to stop routing through codex-lb without touching `auth.json`, use the lighter `sks codex-lb unselect` instead:
 
 ```sh

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "sneakoscope",
   "displayName": "ㅅㅋㅅ",
-  "version": "0.9.8",
+  "version": "0.9.10",
   "description": "Sneakoscope Codex: database-safe Codex CLI/App harness with Team, Goal, AutoResearch, TriWiki, and Honest Mode.",
   "type": "module",
   "homepage": "https://github.com/mandarange/Sneakoscope-Codex#readme",

package/src/cli/install-helpers.mjs

@@ -9,6 +9,7 @@ import { formatHarnessConflictReport, llmHarnessCleanupPrompt, scanHarnessConfli
 import { initProject, installSkills } from '../core/init.mjs';
 import { context7ConfigToml, DOLLAR_SKILL_NAMES, GETDESIGN_REFERENCE, hasContext7ConfigText, RECOMMENDED_SKILLS } from '../core/routes.mjs';
 import { codexLaunchCommand, platformTmuxInstallHint, tmuxReadiness } from '../core/tmux-ui.mjs';
+import { reconcileCodexAppUpgradeProcesses } from '../core/codex-app.mjs';
 
 const DEFAULT_CODEX_APP_PLUGINS = [
   ['browser', 'openai-bundled'],
@@ -46,6 +47,11 @@ export async function postinstall({ bootstrap }) {
   else if (fastModeRepair.status === 'present') console.log('Codex App Fast mode: config already compatible.');
   else if (fastModeRepair.status === 'skipped') console.log(`Codex App Fast mode: skipped (${fastModeRepair.reason}).`);
   else if (fastModeRepair.status === 'failed') console.log(`Codex App Fast mode: auto repair failed. Run \`sks setup\`. ${fastModeRepair.error || ''}`.trim());
+  const appProcessRepair = await reconcileCodexAppUpgradeProcesses();
+  if (appProcessRepair.status === 'repaired') console.log(`Codex App reconnect repair: stopped ${appProcessRepair.killed.length} stale orphan app-server process(es). Restart Codex App to reconnect cleanly.`);
+  else if (appProcessRepair.status === 'partial') console.log(`Codex App reconnect repair: stopped ${appProcessRepair.killed.length} stale orphan app-server process(es); ${appProcessRepair.failed.length} could not be stopped. Restart Codex App if reconnecting continues.`);
+  else if (appProcessRepair.status === 'skipped' && appProcessRepair.reason !== 'platform') console.log(`Codex App reconnect repair: skipped (${appProcessRepair.reason}).`);
+  else if (appProcessRepair.status === 'failed') console.log(`Codex App reconnect repair: skipped (${appProcessRepair.error || appProcessRepair.reason || 'process check failed'}).`);
   const globalSkills = await ensureGlobalCodexSkillsDuringInstall();
   if (globalSkills.status === 'installed') {
     const removed = globalSkills.removed_stale_generated_skills || [];
@@ -88,8 +94,12 @@ async function reportPostinstallCodexLbAuth() {
   else if (codexLbAuth.status === 'missing_base_url') console.log('codex-lb auth: stored key has no recoverable base URL. Run `sks codex-lb reconfigure --host <domain> --api-key <key>` once.');
   else if (codexLbAuth.status && codexLbAuth.status !== 'not_configured') console.log(`codex-lb auth: repair skipped (${codexLbAuth.status}${codexLbAuth.error ? `: ${codexLbAuth.error}` : ''}).`);
   const reconcile = codexLbAuth.auth_reconcile;
-  if (reconcile?.status === 'reconciled') {
-    console.log(`codex-lb auth: resolved ChatGPT OAuth conflict by switching auth.json to apikey mode (OAuth backup at ${reconcile.backup_path}). Set SKS_CODEX_LB_NO_AUTH_RECONCILE=1 to opt out.`);
+  if (reconcile?.status === 'oauth_preserved') {
+    console.log(`codex-lb auth: ChatGPT OAuth preserved for Codex App; codex-lb key stays in env_key (OAuth backup at ${reconcile.backup_path}).`);
+  } else if (reconcile?.status === 'oauth_restored') {
+    console.log(`codex-lb auth: restored ChatGPT OAuth from ${reconcile.backup_path} while keeping codex-lb selected.`);
+  } else if (reconcile?.status === 'apikey_forced') {
+    console.log(`codex-lb auth: forced API-key auth.json for CLI-only use (OAuth backup at ${reconcile.backup_path}).`);
   } else if (reconcile?.status === 'backup_only') {
     console.log(`codex-lb auth: detected ChatGPT OAuth tokens in auth.json. OAuth backup written to ${reconcile.backup_path}; auth.json left untouched because SKS_CODEX_LB_NO_AUTH_RECONCILE=1.`);
   } else if (reconcile?.status === 'failed') {
@@ -263,6 +273,9 @@ export async function configureCodexLb(opts = {}) {
   await fsp.chmod(envPath, 0o600).catch(() => {});
   const codexEnvironment = await syncCodexLbProviderEnvironment({ env_path: envPath, base_url: baseUrl }, { ...opts, home });
   const codexLogin = await maybeSyncCodexLbSharedLogin(apiKey, { ...opts, home, force: true });
+  const codexLb = await codexLbStatus({ ...opts, home, configPath, envPath });
+  const authReconcile = await reconcileCodexLbAuthConflict({ ...opts, home, status: codexLb }).catch((err) => ({ status: 'failed', reason: 'exception', error: err.message }));
+  const finalCodexLb = await codexLbStatus({ ...opts, home, configPath, envPath });
   const ok = Boolean(codexEnvironment.ok && codexLogin.ok);
   return {
     ok,
@@ -271,9 +284,11 @@ export async function configureCodexLb(opts = {}) {
     env_path: envPath,
     base_url: baseUrl,
     env_key: 'CODEX_LB_API_KEY',
+    auth_reconcile: authReconcile,
+    codex_lb: finalCodexLb,
     codex_environment: codexEnvironment,
     codex_login: codexLogin,
-    error: codexEnvironment.error || codexLogin.error || null
+    error: authReconcile.error || codexEnvironment.error || codexLogin.error || null
   };
 }
 
@@ -284,6 +299,9 @@ export async function codexLbStatus(opts = {}) {
   const config = await readText(configPath, '');
   const envExists = await exists(envPath);
   const envText = envExists ? await readText(envPath, '') : '';
+  const authPath = opts.authPath || codexAuthPath(home);
+  const authText = await readText(authPath, '');
+  const authMode = codexAuthModeSummary(authText);
   const envKeyConfigured = Boolean(parseCodexLbEnvKey(envText));
   const providerConfigured = /\[model_providers\.codex-lb\]/.test(config);
   const selected = hasTopLevelCodexLbSelected(config);
@@ -299,10 +317,52 @@ export async function codexLbStatus(opts = {}) {
     env_file: envExists,
     env_key_configured: envKeyConfigured,
     env_base_url_configured: Boolean(parseCodexLbEnvBaseUrl(envText)),
-    base_url: baseUrl
+    base_url: baseUrl,
+    auth_path: authPath,
+    auth_mode: authMode.mode,
+    auth_usable_for_codex_app: authMode.codex_app_usable,
+    auth_summary: authMode.summary
   };
 }
 
+export function formatCodexLbStatusText(status = {}, opts = {}) {
+  const backupPresent = Boolean(opts.backupPresent);
+  const backupPath = opts.backupPath || '';
+  const lines = [
+    'SKS codex-lb',
+    '',
+    `Configured: ${status.ok ? 'yes' : 'no'}`,
+    `Selected:   ${status.selected ? 'yes' : 'no'}`,
+    `Provider:   ${status.provider_configured ? 'yes' : 'no'}`,
+    `Provider requires OpenAI auth: ${status.provider_requires_openai_auth ? 'yes' : 'missing'}`,
+    `Codex App auth: ${status.auth_usable_for_codex_app ? 'ok' : 'needs sign-in/repair'} (${status.auth_mode || 'unknown'})`
+  ];
+  if (status.auth_summary) lines.push(`Auth detail: ${status.auth_summary}`);
+  lines.push(`Env file:   ${status.env_file ? status.env_path : 'missing'}`);
+  if (status.base_url) lines.push(`Base URL:   ${status.base_url}`);
+  lines.push(`ChatGPT backup: ${backupPresent ? `yes (${backupPath})` : 'no'}`);
+  if (status.ok && !status.auth_usable_for_codex_app && backupPresent) lines.push('', 'Run: sks codex-lb repair to restore the ChatGPT OAuth backup while keeping codex-lb selected.');
+  else if (status.ok && !status.auth_usable_for_codex_app) lines.push('', 'Sign in to Codex App/CLI again, then run: sks codex-lb repair');
+  else if (status.ok && !status.selected) lines.push('', 'Run: sks codex-lb repair to activate codex-lb for Codex App.');
+  else if (!status.ok && status.base_url && status.env_key_configured) lines.push('', 'Run: sks codex-lb repair to restore the upstream codex-lb provider block.');
+  else if (!status.ok) lines.push('', 'Run: sks codex-lb setup --host <domain> --api-key <key>');
+  else lines.push('', 'Repair provider auth: sks codex-lb repair');
+  if (backupPresent) lines.push('Switch fully away from codex-lb: sks codex-lb release');
+  return `${lines.join('\n')}\n`;
+}
+
+export function formatCodexLbRepairResultText(result = {}) {
+  const lines = [
+    'codex-lb provider auth repaired for Codex CLI/App environment.',
+    `Config: ${result.config_path}`,
+    `Key env: ${result.env_path}`
+  ];
+  if (result.auth_reconcile?.status === 'oauth_restored') lines.push(`Codex App auth: ChatGPT OAuth restored from ${result.auth_reconcile.backup_path}.`);
+  else if (result.auth_reconcile?.status === 'oauth_preserved') lines.push('Codex App auth: ChatGPT OAuth preserved; codex-lb will use CODEX_LB_API_KEY from env_key.');
+  else if (result.auth_reconcile?.status === 'apikey_auth_active') lines.push('Codex App auth: API-key auth.json is still active. Sign in again if the App asks for ChatGPT OAuth.');
+  return `${lines.join('\n')}\n`;
+}
+
 function codexLbResponsesEndpoint(baseUrl = '') {
   const base = String(baseUrl || '').trim().replace(/\/+$/, '');
   if (!base) return '';
@@ -313,6 +373,77 @@ function codexLbChainCheckEnabled(env = process.env) {
   return env.SKS_CODEX_LB_CHAIN_CHECK !== '0' && env.SKS_SKIP_CODEX_LB_CHAIN_CHECK !== '1';
 }
 
+function codexLbChainCachePath(home = process.env.HOME || os.homedir()) {
+  return path.join(home, '.codex', 'sks-codex-lb-chain-health.json');
+}
+
+function codexLbChainCacheTtlMs(status = '', env = process.env) {
+  const hardFailure = Boolean(status && !['chain_ok', 'previous_response_not_found'].includes(status));
+  const key = hardFailure ? 'SKS_CODEX_LB_CHAIN_CHECK_FAILURE_CACHE_TTL_MS' : 'SKS_CODEX_LB_CHAIN_CHECK_CACHE_TTL_MS';
+  const fallback = hardFailure ? 30 * 1000 : 5 * 60 * 1000;
+  const raw = env[key] ?? env.SKS_CODEX_LB_CHAIN_CHECK_CACHE_TTL_MS;
+  if (raw === undefined || raw === '') return fallback;
+  const parsed = Number(raw);
+  return Number.isFinite(parsed) ? Math.max(0, parsed) : fallback;
+}
+
+function codexLbChainCacheEnabled(opts = {}, env = process.env) {
+  if (opts.force || opts.cache === false) return false;
+  if (opts.fetch) return false;
+  if (env.SKS_CODEX_LB_CHAIN_CHECK_CACHE === '0') return false;
+  return true;
+}
+
+async function readCodexLbChainCache({ endpoint, home, opts = {}, env = process.env } = {}) {
+  if (!endpoint || !codexLbChainCacheEnabled(opts, env)) return null;
+  const cachePath = opts.cachePath || codexLbChainCachePath(home || env.HOME || os.homedir());
+  const text = await readText(cachePath, '');
+  if (!text.trim()) return null;
+  try {
+    const parsed = JSON.parse(text);
+    if (parsed?.schema !== 'sks.codex-lb-chain-health.v1' || parsed.endpoint !== endpoint || !parsed.result?.status) return null;
+    const now = typeof opts.now === 'function' ? opts.now() : Date.now();
+    const checkedAt = Number(parsed.checked_at_ms || 0);
+    const ttlMs = codexLbChainCacheTtlMs(parsed.result.status, env);
+    if (!checkedAt || ttlMs <= 0 || now - checkedAt > ttlMs) return null;
+    return {
+      ...parsed.result,
+      endpoint,
+      cached: true,
+      cache_path: cachePath,
+      cache_age_ms: Math.max(0, now - checkedAt)
+    };
+  } catch {
+    return null;
+  }
+}
+
+async function writeCodexLbChainCache(result = {}, { endpoint, home, opts = {}, env = process.env } = {}) {
+  if (!endpoint || !result.status || !codexLbChainCacheEnabled(opts, env)) return result;
+  const cachePath = opts.cachePath || codexLbChainCachePath(home || env.HOME || os.homedir());
+  const now = typeof opts.now === 'function' ? opts.now() : Date.now();
+  const cacheResult = {
+    ok: Boolean(result.ok),
+    status: result.status,
+    chain_unhealthy: result.chain_unhealthy === true,
+    http_status: result.http_status || null,
+    error: result.error || null
+  };
+  try {
+    await ensureDir(path.dirname(cachePath));
+    await writeTextAtomic(cachePath, `${JSON.stringify({
+      schema: 'sks.codex-lb-chain-health.v1',
+      endpoint,
+      checked_at_ms: now,
+      result: cacheResult
+    }, null, 2)}\n`);
+    await fsp.chmod(cachePath, 0o600).catch(() => {});
+  } catch {
+    // Cache writes are a launch optimization only; never block codex-lb startup.
+  }
+  return result;
+}
+
 function isPreviousResponseNotFound(payload = {}) {
   const error = payload?.error || payload?.response?.error || payload;
   const text = typeof error === 'string'
@@ -382,8 +513,11 @@ export async function checkCodexLbResponseChain(status = {}, opts = {}) {
   if (!codexLbChainCheckEnabled(env) && !opts.force) return { ok: true, status: 'skipped', skipped: true, reason: 'SKS_CODEX_LB_CHAIN_CHECK=0' };
   const endpoint = codexLbResponsesEndpoint(opts.baseUrl || status.base_url);
   if (!endpoint) return { ok: false, status: 'missing_base_url', chain_unhealthy: true };
-  const apiKey = opts.apiKey || parseCodexLbEnvKey(await readText(opts.envPath || status.env_path || codexLbEnvPath(opts.home || env.HOME || os.homedir()), ''));
+  const home = opts.home || env.HOME || os.homedir();
+  const apiKey = opts.apiKey || parseCodexLbEnvKey(await readText(opts.envPath || status.env_path || codexLbEnvPath(home), ''));
   if (!apiKey) return { ok: false, status: 'missing_env_key', chain_unhealthy: true };
+  const cached = await readCodexLbChainCache({ endpoint, home, opts, env });
+  if (cached) return cached;
   const fetchImpl = opts.fetch || globalThis.fetch;
   if (typeof fetchImpl !== 'function') return { ok: true, status: 'skipped', skipped: true, reason: 'fetch unavailable' };
   const model = opts.model || env.SKS_CODEX_MODEL || 'gpt-5.5';
@@ -400,19 +534,19 @@ export async function checkCodexLbResponseChain(status = {}, opts = {}) {
   };
   const first = await fetchCodexLbResponse(fetchImpl, endpoint, apiKey, baseBody, timeoutMs);
   if (!first.ok || !first.response_id) {
-    return {
+    return writeCodexLbChainCache({
       ok: false,
       status: first.ok ? 'missing_response_id' : 'first_request_failed',
       chain_unhealthy: true,
       endpoint,
       http_status: first.status,
       error: redactSecretText(first.error_payload?.error?.message || first.error_payload?.response?.error?.message || first.text || 'codex-lb first Responses request failed', [apiKey])
-    };
+    }, { endpoint, home, opts, env });
   }
   const second = await fetchCodexLbResponse(fetchImpl, endpoint, apiKey, { ...baseBody, previous_response_id: first.response_id }, timeoutMs);
-  if (second.ok) return { ok: true, status: 'chain_ok', endpoint, response_id: first.response_id, chained_response_id: second.response_id || null, http_status: second.status };
+  if (second.ok) return writeCodexLbChainCache({ ok: true, status: 'chain_ok', endpoint, response_id: first.response_id, chained_response_id: second.response_id || null, http_status: second.status }, { endpoint, home, opts, env });
   const previousMissing = isPreviousResponseNotFound(second.error_payload || second.json || second.text);
-  return {
+  return writeCodexLbChainCache({
     ok: false,
     status: previousMissing ? 'previous_response_not_found' : 'second_request_failed',
     chain_unhealthy: true,
@@ -420,7 +554,7 @@ export async function checkCodexLbResponseChain(status = {}, opts = {}) {
     response_id: first.response_id,
     http_status: second.status,
     error: redactSecretText(second.error_payload?.error?.message || second.error_payload?.response?.error?.message || second.text || 'codex-lb chained Responses request failed', [apiKey])
-  };
+  }, { endpoint, home, opts, env });
 }
 
 function hasTopLevelCodexLbSelected(text = '') {
@@ -473,6 +607,7 @@ export async function repairCodexLbAuth(opts = {}) {
   const apiKey = parseCodexLbEnvKey(await readText(status.env_path, ''));
   const codexLogin = await maybeSyncCodexLbSharedLogin(apiKey, { ...opts, home: opts.home || process.env.HOME || os.homedir(), force: true });
   const authReconcile = await reconcileCodexLbAuthConflict({ ...opts, status }).catch((err) => ({ status: 'failed', reason: 'exception', error: err.message }));
+  const finalStatus = await codexLbStatus(opts);
   const ok = Boolean(codexEnvironment.ok && codexLogin.ok);
   return {
     ok,
@@ -484,7 +619,7 @@ export async function repairCodexLbAuth(opts = {}) {
     legacy_auth_migrated: legacyAuthMigrated,
     legacy_auth_path: legacyAuthPath,
     auth_reconcile: authReconcile,
-    codex_lb: status,
+    codex_lb: finalStatus,
     codex_environment: codexEnvironment,
     codex_login: codexLogin
   };
@@ -504,6 +639,7 @@ export async function ensureCodexLbAuthDuringInstall(opts = {}) {
   const apiKey = parseCodexLbEnvKey(await readText(status.env_path, ''));
   const codexLogin = await maybeSyncCodexLbSharedLogin(apiKey, { ...opts, home: opts.home || process.env.HOME || os.homedir(), force: true });
   const authReconcile = await reconcileCodexLbAuthConflict({ ...opts, status }).catch((err) => ({ status: 'failed', reason: 'exception', error: err.message }));
+  const finalStatus = await codexLbStatus(opts);
   const ok = Boolean(codexEnvironment.ok && codexLogin.ok);
   return {
     ok,
@@ -511,7 +647,7 @@ export async function ensureCodexLbAuthDuringInstall(opts = {}) {
     config_path: status.config_path,
     env_path: status.env_path,
     base_url: status.base_url,
-    codex_lb: status,
+    codex_lb: finalStatus,
     codex_environment: codexEnvironment,
     codex_login: codexLogin,
     auth_reconcile: authReconcile,
@@ -565,6 +701,19 @@ function parseCodexAuthApiKey(text = '') {
   }
 }
 
+function codexAuthModeSummary(text = '') {
+  const raw = String(text || '').trim();
+  if (!raw) return { mode: 'missing', codex_app_usable: false, summary: 'missing auth.json' };
+  if (hasChatgptOAuthTokens(raw)) return { mode: 'chatgpt_oauth', codex_app_usable: true, summary: 'ChatGPT OAuth token blob present' };
+  const apiKey = parseCodexAuthApiKey(raw);
+  if (apiKey) return { mode: 'apikey', codex_app_usable: false, summary: 'API-key auth.json; Codex App may require ChatGPT sign-in for requires_openai_auth providers' };
+  try {
+    const parsed = JSON.parse(raw);
+    if (parsed?.auth_mode === 'browser') return { mode: 'browser_marker', codex_app_usable: false, summary: 'browser auth marker without refresh tokens' };
+  } catch {}
+  return { mode: 'unknown', codex_app_usable: false, summary: 'unrecognized auth.json shape' };
+}
+
 // Migrate auth.json from legacy {"auth_mode":"apikey","key":"..."} to the codex 0.130.0+
 // format {"auth_mode":"apikey","OPENAI_API_KEY":"..."}. Safe: preserves key value, only renames field.
 async function migrateCodexAuthKeyFormat(opts = {}) {
@@ -587,11 +736,10 @@ async function migrateCodexAuthKeyFormat(opts = {}) {
   }
 }
 
-// When codex-lb is selected with env_key auth AND auth.json also carries a real ChatGPT OAuth
-// token blob, Codex CLI/App can pick the OAuth bearer over the env_key bearer and fail against
-// the load balancer. We back the OAuth blob up to ~/.codex/auth.chatgpt-backup.json and replace
-// auth.json with an apikey-mode payload that matches the stored CODEX_LB_API_KEY.
-// Opt out with SKS_CODEX_LB_NO_AUTH_RECONCILE=1 (the backup is still produced so nothing is lost).
+// Codex App needs a refreshable ChatGPT OAuth blob when a provider declares
+// requires_openai_auth=true. For codex-lb, the proxy key belongs in env_key
+// (CODEX_LB_API_KEY), so SKS preserves or restores OAuth by default and only
+// writes apikey auth.json when explicitly requested for CLI-only legacy use.
 export async function reconcileCodexLbAuthConflict(opts = {}) {
   const home = opts.home || process.env.HOME || os.homedir();
   const status = opts.status || await codexLbStatus({ ...opts, home });
@@ -607,42 +755,77 @@ export async function reconcileCodexLbAuthConflict(opts = {}) {
   if (!authText.trim()) {
     return { status: 'skipped', reason: 'auth_empty', auth_path: authPath };
   }
-  if (!hasChatgptOAuthTokens(authText)) {
-    return { status: 'no_oauth_conflict', auth_path: authPath };
-  }
   const envText = await readText(status.env_path, '');
   const apiKey = parseCodexLbEnvKey(envText);
   if (!apiKey) {
     return { status: 'skipped', reason: 'missing_env_key', auth_path: authPath };
   }
-  // Always back up the OAuth blob — even if reconciliation is opted out — so the data survives.
-  try {
-    await ensureDir(path.dirname(backupPath));
-    await writeTextAtomic(backupPath, authText);
-    await fsp.chmod(backupPath, 0o600).catch(() => {});
-  } catch (err) {
-    return { status: 'failed', reason: 'backup_failed', auth_path: authPath, backup_path: backupPath, error: err.message };
-  }
-  if (process.env.SKS_CODEX_LB_NO_AUTH_RECONCILE === '1' && !opts.force) {
+  if (hasChatgptOAuthTokens(authText)) {
+    try {
+      await ensureDir(path.dirname(backupPath));
+      await writeTextAtomic(backupPath, authText);
+      await fsp.chmod(backupPath, 0o600).catch(() => {});
+    } catch (err) {
+      return { status: 'failed', reason: 'backup_failed', auth_path: authPath, backup_path: backupPath, error: err.message };
+    }
+    if (process.env.SKS_CODEX_LB_NO_AUTH_RECONCILE === '1' && !opts.force) {
+      return {
+        status: 'backup_only',
+        reason: 'SKS_CODEX_LB_NO_AUTH_RECONCILE=1',
+        auth_path: authPath,
+        backup_path: backupPath
+      };
+    }
+    if (process.env.SKS_CODEX_LB_FORCE_APIKEY_AUTH !== '1') {
+      return {
+        status: 'oauth_preserved',
+        reason: 'codex_app_requires_refreshable_oauth',
+        auth_path: authPath,
+        backup_path: backupPath
+      };
+    }
+    try {
+      const replacement = `${JSON.stringify({ auth_mode: 'apikey', OPENAI_API_KEY: apiKey }, null, 2)}\n`;
+      await writeTextAtomic(authPath, replacement);
+      await fsp.chmod(authPath, 0o600).catch(() => {});
+    } catch (err) {
+      return { status: 'failed', reason: 'write_failed', auth_path: authPath, backup_path: backupPath, error: err.message };
+    }
     return {
-      status: 'backup_only',
-      reason: 'SKS_CODEX_LB_NO_AUTH_RECONCILE=1',
+      status: 'apikey_forced',
+      reason: 'SKS_CODEX_LB_FORCE_APIKEY_AUTH=1',
       auth_path: authPath,
       backup_path: backupPath
     };
   }
-  try {
-    const replacement = `${JSON.stringify({ auth_mode: 'apikey', OPENAI_API_KEY: apiKey }, null, 2)}\n`;
-    await writeTextAtomic(authPath, replacement);
-    await fsp.chmod(authPath, 0o600).catch(() => {});
-  } catch (err) {
-    return { status: 'failed', reason: 'write_failed', auth_path: authPath, backup_path: backupPath, error: err.message };
+
+  const currentApiKey = parseCodexAuthApiKey(authText);
+  if (currentApiKey && currentApiKey === apiKey) {
+    const backupText = await readText(backupPath, '');
+    if (hasChatgptOAuthTokens(backupText) && process.env.SKS_CODEX_LB_KEEP_APIKEY_AUTH !== '1') {
+      try {
+        const restored = backupText.endsWith('\n') ? backupText : `${backupText}\n`;
+        await writeTextAtomic(authPath, restored);
+        await fsp.chmod(authPath, 0o600).catch(() => {});
+        return {
+          status: 'oauth_restored',
+          reason: 'restored_chatgpt_oauth_for_codex_app',
+          auth_path: authPath,
+          backup_path: backupPath
+        };
+      } catch (err) {
+        return { status: 'failed', reason: 'restore_failed', auth_path: authPath, backup_path: backupPath, error: err.message };
+      }
+    }
+    return {
+      status: 'apikey_auth_active',
+      reason: hasChatgptOAuthTokens(backupText) ? 'SKS_CODEX_LB_KEEP_APIKEY_AUTH=1' : 'chatgpt_oauth_backup_missing',
+      auth_path: authPath,
+      backup_path: backupPath
+    };
   }
-  return {
-    status: 'reconciled',
-    auth_path: authPath,
-    backup_path: backupPath
-  };
+
+  return { status: 'no_oauth_conflict', auth_path: authPath };
 }
 
 // Expose the ChatGPT OAuth backup path so the CLI can surface it in status / release output.
@@ -1589,6 +1772,7 @@ function codexLbPostinstallEnv(baseEnv, overrides = {}) {
     SKS_SKIP_POSTINSTALL_GLOBAL_SKILLS: '1',
     SKS_SKIP_POSTINSTALL_CODEX_LB_AUTH: '0',
     SKS_SKIP_CODEX_LB_LAUNCH_ENV: '1',
+    SKS_SKIP_CODEX_APP_UPGRADE_REPAIR: '1',
     ...overrides
   };
 }
@@ -1661,7 +1845,7 @@ export async function selftestCodexLb(tmp) {
   const codexLbPostinstallAuth = await safeReadText(path.join(codexLbHome, '.codex', 'auth.json'));
   const codexLbLoginCallsAfterPostinstall = await codexLbLoginCallCount(codexLbHome);
   if (!String(codexLbPostinstall.stdout || '').includes('codex-lb auth: preserved') || !codexLbPostinstallAuth.includes('"auth_mode":"browser"') || codexLbPostinstallAuth.includes('sk-test') || codexLbLoginCallsAfterPostinstall !== codexLbLoginCallsBeforePostinstall) throw new Error('selftest: postinstall auth');
-  const postinstallEnvKeys = ['HOME', 'PATH', 'INIT_CWD', 'SKS_GLOBAL_ROOT', 'SKS_POSTINSTALL_BOOTSTRAP', 'SKS_POSTINSTALL_NO_BOOTSTRAP', 'SKS_SKIP_POSTINSTALL_SHIM', 'SKS_SKIP_POSTINSTALL_CONTEXT7', 'SKS_SKIP_POSTINSTALL_GETDESIGN', 'SKS_SKIP_POSTINSTALL_GLOBAL_SKILLS', 'SKS_SKIP_POSTINSTALL_CODEX_LB_AUTH', 'SKS_SKIP_CODEX_LB_LAUNCH_ENV', 'SKS_CODEX_LB_SYNC_CODEX_LOGIN'];
+  const postinstallEnvKeys = ['HOME', 'PATH', 'INIT_CWD', 'SKS_GLOBAL_ROOT', 'SKS_POSTINSTALL_BOOTSTRAP', 'SKS_POSTINSTALL_NO_BOOTSTRAP', 'SKS_SKIP_POSTINSTALL_SHIM', 'SKS_SKIP_POSTINSTALL_CONTEXT7', 'SKS_SKIP_POSTINSTALL_GETDESIGN', 'SKS_SKIP_POSTINSTALL_GLOBAL_SKILLS', 'SKS_SKIP_POSTINSTALL_CODEX_LB_AUTH', 'SKS_SKIP_CODEX_LB_LAUNCH_ENV', 'SKS_SKIP_CODEX_APP_UPGRADE_REPAIR', 'SKS_CODEX_LB_SYNC_CODEX_LOGIN'];
   const postinstallEnvBefore = Object.fromEntries(postinstallEnvKeys.map((key) => [key, process.env[key]]));
   const codexLbLoginCallsBeforeBootstrap = await codexLbLoginCallCount(codexLbHome);
   try {
@@ -1677,7 +1861,8 @@ export async function selftestCodexLb(tmp) {
       SKS_SKIP_POSTINSTALL_GETDESIGN: '1',
       SKS_SKIP_POSTINSTALL_GLOBAL_SKILLS: '1',
       SKS_SKIP_POSTINSTALL_CODEX_LB_AUTH: '0',
-      SKS_SKIP_CODEX_LB_LAUNCH_ENV: '1'
+      SKS_SKIP_CODEX_LB_LAUNCH_ENV: '1',
+      SKS_SKIP_CODEX_APP_UPGRADE_REPAIR: '1'
     });
     await postinstall({
       bootstrap: async () => {
@@ -1730,7 +1915,7 @@ export async function selftestCodexLb(tmp) {
   const codexLbReconcileJson = JSON.parse(codexLbReconcileRepair.stdout);
   const codexLbReconcileAuth = await safeReadText(path.join(codexLbHome, '.codex', 'auth.json'));
   const codexLbReconcileBackup = await safeReadText(path.join(codexLbHome, '.codex', 'auth.chatgpt-backup.json'));
-  if (codexLbReconcileJson.auth_reconcile?.status !== 'reconciled' || !codexLbReconcileAuth.includes('"auth_mode": "apikey"') || !codexLbReconcileAuth.includes('sk-test') || codexLbReconcileAuth.includes('oauth-id') || !codexLbReconcileBackup.includes('oauth-id') || !codexLbReconcileBackup.includes('oauth-refresh')) throw new Error('selftest: codex-lb oauth reconcile did not back up ChatGPT tokens and switch auth.json to apikey mode');
+  if (codexLbReconcileJson.auth_reconcile?.status !== 'oauth_preserved' || !codexLbReconcileAuth.includes('oauth-id') || !codexLbReconcileAuth.includes('oauth-refresh') || codexLbReconcileAuth.includes('sk-test') || !codexLbReconcileBackup.includes('oauth-id') || !codexLbReconcileBackup.includes('oauth-refresh')) throw new Error('selftest: codex-lb oauth reconcile should preserve ChatGPT OAuth and back it up');
   // Opt-out path: SKS_CODEX_LB_NO_AUTH_RECONCILE=1 keeps auth.json untouched but still backs up the OAuth blob.
   await writeTextAtomic(path.join(codexLbHome, '.codex', 'auth.json'), `${oauthAuthJson}\n`);
   await fsp.rm(path.join(codexLbHome, '.codex', 'auth.chatgpt-backup.json'), { force: true });
@@ -1740,6 +1925,16 @@ export async function selftestCodexLb(tmp) {
   const codexLbReconcileOptOutAuth = await safeReadText(path.join(codexLbHome, '.codex', 'auth.json'));
   const codexLbReconcileOptOutBackup = await safeReadText(path.join(codexLbHome, '.codex', 'auth.chatgpt-backup.json'));
   if (codexLbReconcileOptOutJson.auth_reconcile?.status !== 'backup_only' || !codexLbReconcileOptOutAuth.includes('oauth-id') || !codexLbReconcileOptOutBackup.includes('oauth-id')) throw new Error('selftest: codex-lb oauth reconcile opt-out should back up but not rewrite auth.json');
+  // Restore path: older SKS versions could leave the codex-lb API key in auth.json. Repair should
+  // restore the ChatGPT OAuth backup while keeping codex-lb selected for provider routing.
+  await writeTextAtomic(path.join(codexLbHome, '.codex', 'auth.json'), '{"auth_mode":"apikey","OPENAI_API_KEY":"sk-test"}\n');
+  await writeTextAtomic(path.join(codexLbHome, '.codex', 'auth.chatgpt-backup.json'), `${oauthAuthJson}\n`);
+  const codexLbReconcileRestoreRepair = await runProcess(process.execPath, [path.join(packageRoot(), 'bin', 'sks.mjs'), 'auth', 'repair', '--json'], { cwd: tmp, env: codexLbEnvForSelftest, timeoutMs: 15000, maxOutputBytes: 64 * 1024 });
+  if (codexLbReconcileRestoreRepair.code !== 0) throw new Error(`selftest: codex-lb oauth restore repair exited ${codexLbReconcileRestoreRepair.code}: ${codexLbReconcileRestoreRepair.stderr}`);
+  const codexLbReconcileRestoreJson = JSON.parse(codexLbReconcileRestoreRepair.stdout);
+  const codexLbReconcileRestoreAuth = await safeReadText(path.join(codexLbHome, '.codex', 'auth.json'));
+  const codexLbReconcileRestoreConfig = await safeReadText(path.join(codexLbHome, '.codex', 'config.toml'));
+  if (codexLbReconcileRestoreJson.auth_reconcile?.status !== 'oauth_restored' || !codexLbReconcileRestoreAuth.includes('oauth-id') || codexLbReconcileRestoreAuth.includes('sk-test') || !hasTopLevelCodexLbSelected(codexLbReconcileRestoreConfig)) throw new Error('selftest: codex-lb oauth restore should replace apikey auth.json with ChatGPT OAuth backup while keeping codex-lb selected');
   // codex-lb auth: release flow — restore ChatGPT OAuth from backup so the user can return to
   // the official ChatGPT account login. Default deselects model_provider; flags control whether
   // the provider stays selected and whether the backup file is removed after restore.
@@ -1932,7 +2127,7 @@ export async function selftestCodexLb(tmp) {
   });
   if (codexLbNotConfigured.code !== 0 || String(codexLbNotConfigured.stdout || '').includes('codex-lb auth:')) throw new Error('selftest: postinstall should stay quiet when codex-lb is not configured');
   const codexLbStatusText = await runProcess(process.execPath, [path.join(packageRoot(), 'bin', 'sks.mjs'), 'codex-lb', 'status'], { cwd: tmp, env: codexLbEnvForSelftest, timeoutMs: 15000, maxOutputBytes: 64 * 1024 });
-  if (!String(codexLbStatusText.stdout || '').includes('Repair provider auth: sks codex-lb repair')) throw new Error('selftest: codex-lb status did not advertise repair command');
+  if (!String(codexLbStatusText.stdout || '').includes('Codex App auth:') || !String(codexLbStatusText.stdout || '').includes('sks codex-lb repair')) throw new Error('selftest: codex-lb status did not advertise App auth state and repair command');
   const nonInteractiveLaunchChainCalls = [];
   const nonInteractiveLaunch = await maybePromptCodexLbSetupForLaunch([], {
     home: codexLbHome,
@@ -2023,6 +2218,21 @@ export async function selftestCodexLb(tmp) {
     }
   );
   if (!okChain.ok || okChain.status !== 'chain_ok' || chainCalls.length !== 2 || !String(chainCalls[0].url).endsWith('/backend-api/codex/responses') || chainCalls[1].body.previous_response_id !== 'resp_selftest_1') throw new Error('selftest: codex-lb response chain health check did not verify previous_response_id continuity');
+  const previousGlobalFetch = globalThis.fetch;
+  const cacheCalls = [];
+  const cachePath = path.join(codexLbHome, '.codex', 'chain-cache-selftest.json');
+  try {
+    globalThis.fetch = async (url, init) => {
+      cacheCalls.push({ url, body: JSON.parse(init.body) });
+      return new Response(JSON.stringify({ id: cacheCalls.length === 1 ? 'resp_cache_1' : 'resp_cache_2' }), { status: 200, headers: { 'content-type': 'application/json' } });
+    };
+    const cacheStatus = { base_url: 'https://cache.example.test/backend-api/codex', env_path: path.join(codexLbHome, '.codex', 'sks-codex-lb.env') };
+    const firstCache = await checkCodexLbResponseChain(cacheStatus, { home: codexLbHome, apiKey: 'sk-test', timeoutMs: 1000, cachePath, now: () => 1000 });
+    const secondCache = await checkCodexLbResponseChain(cacheStatus, { home: codexLbHome, apiKey: 'sk-test', timeoutMs: 1000, cachePath, now: () => 2000 });
+    if (!firstCache.ok || firstCache.status !== 'chain_ok' || secondCache.cached !== true || secondCache.status !== 'chain_ok' || cacheCalls.length !== 2) throw new Error('selftest: codex-lb response chain cache did not avoid repeated launch preflight calls');
+  } finally {
+    globalThis.fetch = previousGlobalFetch;
+  }
   const brokenChain = await checkCodexLbResponseChain(
     { base_url: 'https://lb.example.test/backend-api/codex', env_path: path.join(codexLbHome, '.codex', 'sks-codex-lb.env') },
     {

package/src/cli/main.mjs

@@ -73,7 +73,7 @@ import { MISTAKE_RECALL_ARTIFACT, contractConsumesMistakeRecall } from '../core/
 import { buildPromptContext } from '../core/prompt-context-builder.mjs';
 import { renderTeamDashboardState, writeTeamDashboardState } from '../core/team-dashboard-renderer.mjs';
 import { GOAL_WORKFLOW_ARTIFACT } from '../core/goal-workflow.mjs';
-import { CODEX_APP_DOCS_URL, codexAccessTokenStatus, codexAppIntegrationStatus, formatCodexAppStatus } from '../core/codex-app.mjs';
+import { CODEX_APP_DOCS_URL, codexAccessTokenStatus, codexAppIntegrationStatus, findCodexAppUpgradeRepairTargets, formatCodexAppStatus, parseProcessRows } from '../core/codex-app.mjs';
 import { buildAllFeaturesSelftest, buildFeatureRegistry, validateFeatureRegistry } from '../core/feature-registry.mjs';
 import { codexAppRemoteControlCommand } from './codex-app-command.mjs';
 import { allFeaturesCommand, featuresCommand, hooksCommand, hooksExplainReport } from './feature-commands.mjs';
@@ -81,7 +81,7 @@ import { OPENCLAW_SKILL_NAME, installOpenClawSkill } from '../core/openclaw.mjs'
 import { buildTmuxLaunchPlan, buildTmuxOpenArgs, codexLaunchCommand, createTmuxSession, defaultCodexLaunchArgs, isTmuxShellSession, runTmuxLaunchPlanSyntaxCheck, shouldAutoAttachTmux, sksAsciiLogo, tmuxReadiness, tmuxStatusKind, defaultTmuxSessionName, formatTmuxBanner, launchMadTmuxUi, launchTmuxTeamView, launchTmuxUi, platformTmuxInstallHint, reconcileTmuxTeamCockpit, runTmuxStatus, sanitizeTmuxSessionName, sweepCodexLbTmuxSessions, sweepTmuxTeamSurfaces, teamLaneStyle } from '../core/tmux-ui.mjs';
 import { autoReviewProfileName, autoReviewStatus, autoReviewSummary, enableAutoReview, disableAutoReview, enableMadHighProfile, madHighProfileName } from '../core/auto-review.mjs';
 import { context7Command } from './context7-command.mjs';
-import { askPostinstallQuestion, checkCodexLbResponseChain, checkContext7, checkRequiredSkills, codexLbChatgptBackupPath, codexLbStatus, configureCodexLb, ensureCodexCliTool, ensureGlobalCodexFastModeDuringInstall, ensureGlobalCodexSkillsDuringInstall, ensureProjectContext7Config, ensureRelatedCliTools, ensureSksCommandDuringInstall, ensureTmuxCliTool, globalCodexSkillsRoot, maybePromptCodexLbSetupForLaunch, maybePromptCodexUpdateForLaunch, postinstall, postinstallBootstrapDecision, releaseCodexLbAuthHold, repairCodexLbAuth, selftestCodexLb, shouldAutoApproveInstall, unselectCodexLbProvider } from './install-helpers.mjs';
+import { askPostinstallQuestion, checkCodexLbResponseChain, checkContext7, checkRequiredSkills, codexLbChatgptBackupPath, codexLbStatus, configureCodexLb, ensureCodexCliTool, ensureGlobalCodexFastModeDuringInstall, ensureGlobalCodexSkillsDuringInstall, ensureProjectContext7Config, ensureRelatedCliTools, ensureSksCommandDuringInstall, ensureTmuxCliTool, formatCodexLbRepairResultText, formatCodexLbStatusText, globalCodexSkillsRoot, maybePromptCodexLbSetupForLaunch, maybePromptCodexUpdateForLaunch, postinstall, postinstallBootstrapDecision, releaseCodexLbAuthHold, repairCodexLbAuth, selftestCodexLb, shouldAutoApproveInstall, unselectCodexLbProvider } from './install-helpers.mjs';
 import { buildTeamPlan, codeStructureCommand, dbCommand, defaultBeta, defaultVGraph, evalCommand, gcCommand, goalCommand, gxCommand, harnessCommand, hproofCommand, madHighCommand as runMadHighCommand, memoryCommand, migrateWikiContextPack, parseTeamCreateArgs, perfCommand, profileCommand, projectWikiClaims, proofFieldCommand, qaLoopCommand, quickstartCommand, researchCommand, skillDreamCommand, statsCommand, team, teamWorkflowMarkdown, validateArtifactsCommand, wikiCommand, wikiVoxelRowCount, writeWikiContextPack } from './maintenance-commands.mjs';
 import { openClawCommand } from './openclaw-command.mjs';
 import { recallPulseCommand } from './recallpulse-command.mjs';
@@ -1150,19 +1150,7 @@ async function codexLbCommand(action = 'status', args = []) {
     const backupPath = codexLbChatgptBackupPath();
     const backupPresent = await exists(backupPath);
     if (json) return console.log(JSON.stringify({ ...status, chatgpt_backup_present: backupPresent, chatgpt_backup_path: backupPath }, null, 2));
-    console.log('SKS codex-lb\n');
-    console.log(`Configured: ${status.ok ? 'yes' : 'no'}`);
-    console.log(`Selected:   ${status.selected ? 'yes' : 'no'}`);
-    console.log(`Provider:   ${status.provider_configured ? 'yes' : 'no'}`);
-    console.log(`Codex App auth: ${status.provider_requires_openai_auth ? 'yes' : 'missing'}`);
-    console.log(`Env file:   ${status.env_file ? status.env_path : 'missing'}`);
-    if (status.base_url) console.log(`Base URL:   ${status.base_url}`);
-    console.log(`ChatGPT backup: ${backupPresent ? `yes (${backupPath})` : 'no'}`);
-    if (status.ok && !status.selected) console.log('\nRun: sks codex-lb repair to activate codex-lb for Codex App.');
-    else if (!status.ok && status.base_url && status.env_key_configured) console.log('\nRun: sks codex-lb repair to restore the upstream codex-lb provider block.');
-    else if (!status.ok) console.log('\nRun: sks codex-lb setup --host <domain> --api-key <key>');
-    else console.log('\nRepair provider auth: sks codex-lb repair');
-    if (backupPresent) console.log('Switch back to ChatGPT OAuth login: sks codex-lb release');
+    process.stdout.write(formatCodexLbStatusText(status, { backupPresent, backupPath }));
     return;
   }
   if (sub === 'release') {
@@ -1248,9 +1236,7 @@ async function codexLbCommand(action = 'status', args = []) {
       process.exitCode = 1;
       return;
     }
-    console.log('codex-lb provider auth repaired for Codex CLI/App environment.');
-    console.log(`Config: ${result.config_path}`);
-    console.log(`Key env: ${result.env_path}`);
+    process.stdout.write(formatCodexLbRepairResultText(result));
     return;
   }
   if (sub === 'setup' || sub === 'reconfigure') {
@@ -2303,11 +2289,11 @@ async function selftest() {
   await ensureDir(path.join(conflictTmp, '.omx'));
   const conflictScan = await scanHarnessConflicts(conflictTmp, { home: path.join(conflictTmp, 'home') });
   if (!conflictScan.hard_block || !formatHarnessConflictReport(conflictScan).includes('GPT-5.5')) throw new Error('selftest: OMX conflict did not block with cleanup prompt');
-  const postinstallConflict = await runProcess(process.execPath, [path.join(packageRoot(), 'bin', 'sks.mjs'), 'postinstall'], { cwd: conflictTmp, env: { INIT_CWD: conflictTmp, HOME: path.join(conflictTmp, 'home'), SKS_SKIP_POSTINSTALL_SHIM: '1', SKS_SKIP_POSTINSTALL_CONTEXT7: '1', SKS_SKIP_POSTINSTALL_GETDESIGN: '1' }, timeoutMs: 15000, maxOutputBytes: 128 * 1024 });
+  const postinstallConflict = await runProcess(process.execPath, [path.join(packageRoot(), 'bin', 'sks.mjs'), 'postinstall'], { cwd: conflictTmp, env: { INIT_CWD: conflictTmp, HOME: path.join(conflictTmp, 'home'), SKS_SKIP_POSTINSTALL_SHIM: '1', SKS_SKIP_POSTINSTALL_CONTEXT7: '1', SKS_SKIP_POSTINSTALL_GETDESIGN: '1', SKS_SKIP_CODEX_APP_UPGRADE_REPAIR: '1' }, timeoutMs: 15000, maxOutputBytes: 128 * 1024 });
   if (postinstallConflict.code !== 0) throw new Error('selftest: postinstall conflict notice should not make npm install fail');
   const postinstallConflictOutput = String(`${postinstallConflict.stdout}\n${postinstallConflict.stderr}`);
   if (!postinstallConflictOutput.includes('SKS setup is blocked') || postinstallConflictOutput.includes('Cleanup prompt:')) throw new Error('selftest: postinstall conflict notice did not stay informational');
-  const postinstallConflictPrompt = await runProcess(process.execPath, [path.join(packageRoot(), 'bin', 'sks.mjs'), 'postinstall'], { cwd: conflictTmp, input: 'y\n', env: { INIT_CWD: conflictTmp, HOME: path.join(conflictTmp, 'home'), SKS_SKIP_POSTINSTALL_SHIM: '1', SKS_SKIP_POSTINSTALL_CONTEXT7: '1', SKS_SKIP_POSTINSTALL_GETDESIGN: '1', SKS_POSTINSTALL_PROMPT: '1' }, timeoutMs: 15000, maxOutputBytes: 128 * 1024 });
+  const postinstallConflictPrompt = await runProcess(process.execPath, [path.join(packageRoot(), 'bin', 'sks.mjs'), 'postinstall'], { cwd: conflictTmp, input: 'y\n', env: { INIT_CWD: conflictTmp, HOME: path.join(conflictTmp, 'home'), SKS_SKIP_POSTINSTALL_SHIM: '1', SKS_SKIP_POSTINSTALL_CONTEXT7: '1', SKS_SKIP_POSTINSTALL_GETDESIGN: '1', SKS_SKIP_CODEX_APP_UPGRADE_REPAIR: '1', SKS_POSTINSTALL_PROMPT: '1' }, timeoutMs: 15000, maxOutputBytes: 128 * 1024 });
   if (postinstallConflictPrompt.code !== 0 || !String(postinstallConflictPrompt.stdout || '').includes('Goal: completely remove the conflicting Codex harnesses')) throw new Error('selftest: conflict prompt');
   const postinstallSetupTmp = tmpdir();
   await writeJsonAtomic(path.join(postinstallSetupTmp, 'package.json'), { name: 'postinstall-setup-smoke', version: '0.0.0' });
@@ -2317,7 +2303,7 @@ async function selftest() {
     await ensureDir(path.join(postinstallSetupHome, '.agents', 'skills', name));
     await writeTextAtomic(path.join(postinstallSetupHome, '.agents', 'skills', name, 'SKILL.md'), stalePluginSkillContent(name));
   }
-  const postinstallSetup = await runProcess(process.execPath, [path.join(packageRoot(), 'bin', 'sks.mjs'), 'postinstall'], { cwd: postinstallSetupTmp, env: { INIT_CWD: postinstallSetupTmp, HOME: path.join(postinstallSetupTmp, 'home'), SKS_SKIP_POSTINSTALL_SHIM: '1', SKS_SKIP_POSTINSTALL_CONTEXT7: '1', SKS_SKIP_POSTINSTALL_GETDESIGN: '1', SKS_SKIP_CLI_TOOLS: '1' }, timeoutMs: 30000, maxOutputBytes: 256 * 1024 });
+  const postinstallSetup = await runProcess(process.execPath, [path.join(packageRoot(), 'bin', 'sks.mjs'), 'postinstall'], { cwd: postinstallSetupTmp, env: { INIT_CWD: postinstallSetupTmp, HOME: path.join(postinstallSetupTmp, 'home'), SKS_SKIP_POSTINSTALL_SHIM: '1', SKS_SKIP_POSTINSTALL_CONTEXT7: '1', SKS_SKIP_POSTINSTALL_GETDESIGN: '1', SKS_SKIP_CODEX_APP_UPGRADE_REPAIR: '1', SKS_SKIP_CLI_TOOLS: '1' }, timeoutMs: 30000, maxOutputBytes: 256 * 1024 });
   if (postinstallSetup.code !== 0) throw new Error(`selftest: postinstall setup exited ${postinstallSetup.code}: ${postinstallSetup.stderr}`);
   if (await exists(path.join(postinstallSetupTmp, '.agents', 'skills', 'agent-team', 'SKILL.md'))) throw new Error('selftest: postinstall installed deprecated agent-team fallback skill');
   if (!String(postinstallSetup.stdout || '').includes('SKS bootstrap: auto-running sks setup --bootstrap --install-scope global --force') || !String(postinstallSetup.stdout || '').includes('SKS Ready')) throw new Error('selftest: postinstall bootstrap');
@@ -2355,7 +2341,7 @@ async function selftest() {
   const postinstallNoMarkerCwd = path.join(postinstallNoMarkerTmp, 'cwd');
   const postinstallNoMarkerGlobalRoot = path.join(postinstallNoMarkerTmp, 'global-root');
   await ensureDir(postinstallNoMarkerCwd);
-  const postinstallNoMarker = await runProcess(process.execPath, [path.join(packageRoot(), 'bin', 'sks.mjs'), 'postinstall'], { cwd: postinstallNoMarkerCwd, env: { INIT_CWD: postinstallNoMarkerCwd, HOME: postinstallNoMarkerHome, SKS_GLOBAL_ROOT: postinstallNoMarkerGlobalRoot, SKS_SKIP_POSTINSTALL_SHIM: '1', SKS_SKIP_POSTINSTALL_CONTEXT7: '1', SKS_SKIP_POSTINSTALL_GETDESIGN: '1', SKS_SKIP_CLI_TOOLS: '1' }, timeoutMs: 30000, maxOutputBytes: 256 * 1024 });
+  const postinstallNoMarker = await runProcess(process.execPath, [path.join(packageRoot(), 'bin', 'sks.mjs'), 'postinstall'], { cwd: postinstallNoMarkerCwd, env: { INIT_CWD: postinstallNoMarkerCwd, HOME: postinstallNoMarkerHome, SKS_GLOBAL_ROOT: postinstallNoMarkerGlobalRoot, SKS_SKIP_POSTINSTALL_SHIM: '1', SKS_SKIP_POSTINSTALL_CONTEXT7: '1', SKS_SKIP_POSTINSTALL_GETDESIGN: '1', SKS_SKIP_CODEX_APP_UPGRADE_REPAIR: '1', SKS_SKIP_CLI_TOOLS: '1' }, timeoutMs: 30000, maxOutputBytes: 256 * 1024 });
   if (postinstallNoMarker.code !== 0) throw new Error(`selftest: no-marker postinstall bootstrap exited ${postinstallNoMarker.code}: ${postinstallNoMarker.stderr}`);
   if (!String(postinstallNoMarker.stdout || '').includes('no project marker found; auto-running global SKS runtime bootstrap')) throw new Error('selftest: no-marker bootstrap');
   if (!(await exists(path.join(postinstallNoMarkerGlobalRoot, '.sneakoscope', 'manifest.json')))) throw new Error('selftest: no-marker postinstall did not bootstrap global runtime root');
@@ -3196,6 +3182,15 @@ async function selftest() {
   const codexAppFixtureOpts = { codex: { bin: fakeCodex, version: 'codex-cli 99.0.0' }, home: appFeatureTmp, cwd: appFeatureTmp, env: { SKS_CODEX_APP_PATH: fakeCodexApp } };
   const codexAppFeatureStatus = await codexAppIntegrationStatus(codexAppFixtureOpts);
   if (!codexAppFeatureStatus.ok || !codexAppFeatureStatus.features?.required_flags_ok || !codexAppFeatureStatus.features?.codex_git_commit || !codexAppFeatureStatus.features?.remote_control || !codexAppFeatureStatus.features?.git_actions?.ok || !codexAppFeatureStatus.features?.fast_mode_config?.ok) throw new Error('selftest: codex-app check did not accept required app feature flags, git actions, remote_control, and unlocked Fast UI config');
+  const codexAppProcessRows = parseProcessRows([
+    '101 1 /Applications/Codex.app/Contents/Resources/codex app-server --analytics-default-enabled',
+    '200 1 /Applications/Codex.app/Contents/MacOS/Codex',
+    '201 200 /Applications/Codex.app/Contents/Resources/codex app-server --analytics-default-enabled',
+    '202 1 /Applications/Codex.app/Contents/Resources/codex app-server --listen stdio://',
+    '203 1 /Users/me/.nvm/versions/node/bin/codex --model gpt-5.5'
+  ].join('\n'));
+  const codexAppRepairTargets = findCodexAppUpgradeRepairTargets(codexAppProcessRows);
+  if (codexAppRepairTargets.length !== 1 || codexAppRepairTargets[0].pid !== 101) throw new Error('selftest: Codex App upgrade repair target selection is not limited to orphan desktop app-server processes');
   const codexAppOldCliStatus = await codexAppIntegrationStatus({ codex: { bin: fakeCodex, version: 'codex-cli 0.129.0' }, home: appFeatureTmp, cwd: appFeatureTmp, env: { SKS_CODEX_APP_PATH: fakeCodexApp } });
   if (codexAppOldCliStatus.ok || codexAppOldCliStatus.features?.git_actions?.ok || !codexAppOldCliStatus.guidance.some((line) => line.includes('git commit/push actions are blocked'))) throw new Error('selftest: codex-app check did not block commit/push actions on old Codex CLI remote-control');
   const missingDefaultPluginTmp = tmpdir();

package/src/core/codex-app.mjs

@@ -238,6 +238,65 @@ export function codexSupportsRemoteControl(versionText) {
   return Boolean(current && compareVersions(current, CODEX_REMOTE_CONTROL_MIN_VERSION) >= 0);
 }
 
+export function parseProcessRows(text = '') {
+  return String(text || '')
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter(Boolean)
+    .map((line) => {
+      const match = line.match(/^(\d+)\s+(\d+)\s+(.+)$/);
+      if (!match) return null;
+      return {
+        pid: Number.parseInt(match[1], 10),
+        ppid: Number.parseInt(match[2], 10),
+        command: match[3]
+      };
+    })
+    .filter((row) => Number.isFinite(row?.pid) && Number.isFinite(row?.ppid) && row.command);
+}
+
+export function findCodexAppUpgradeRepairTargets(rows = []) {
+  return rows.filter((row) => (
+    row?.ppid === 1
+    && /\/Codex\.app\/Contents\/Resources\/codex\s+app-server\s+--analytics-default-enabled(?:\s|$)/.test(String(row.command || ''))
+  ));
+}
+
+export async function reconcileCodexAppUpgradeProcesses(opts = {}) {
+  const platform = opts.platform || process.platform;
+  const env = opts.env || process.env;
+  if (platform !== 'darwin') return { status: 'skipped', reason: 'platform', killed: [] };
+  if (env.SKS_SKIP_CODEX_APP_UPGRADE_REPAIR === '1') return { status: 'skipped', reason: 'SKS_SKIP_CODEX_APP_UPGRADE_REPAIR=1', killed: [] };
+  const run = opts.runProcess || runProcess;
+  const ps = await run('ps', ['-axo', 'pid=', '-o', 'ppid=', '-o', 'command='], {
+    timeoutMs: opts.timeoutMs || 5000,
+    maxOutputBytes: opts.maxOutputBytes || 256 * 1024
+  }).catch((err) => ({ code: 1, stdout: '', stderr: err.message }));
+  if (ps.code !== 0) return { status: 'failed', reason: 'ps_failed', error: ps.stderr || ps.stdout || 'ps exited non-zero', killed: [] };
+  const rows = parseProcessRows(ps.stdout);
+  const targets = findCodexAppUpgradeRepairTargets(rows);
+  const killed = [];
+  const failed = [];
+  for (const target of targets) {
+    if (opts.dryRun) {
+      killed.push({ pid: target.pid, command: target.command, dry_run: true });
+      continue;
+    }
+    const kill = await run('kill', ['-TERM', String(target.pid)], {
+      timeoutMs: opts.timeoutMs || 5000,
+      maxOutputBytes: 8 * 1024
+    }).catch((err) => ({ code: 1, stdout: '', stderr: err.message }));
+    if (kill.code === 0) killed.push({ pid: target.pid, command: target.command });
+    else failed.push({ pid: target.pid, command: target.command, error: kill.stderr || kill.stdout || 'kill exited non-zero' });
+  }
+  return {
+    status: failed.length ? 'partial' : killed.length ? 'repaired' : 'clean',
+    killed,
+    failed,
+    checked: rows.length
+  };
+}
+
 export function formatCodexRemoteControlStatus(status) {
   const lines = [
     'Codex remote-control',

package/src/core/fsx.mjs

@@ -5,7 +5,7 @@ import os from 'node:os';
 import crypto from 'node:crypto';
 import { spawn } from 'node:child_process';
 
-export const PACKAGE_VERSION = '0.9.8';
+export const PACKAGE_VERSION = '0.9.10';
 export const DEFAULT_PROCESS_TAIL_BYTES = 256 * 1024;
 export const DEFAULT_PROCESS_TIMEOUT_MS = 30 * 60 * 1000;