sneakoscope 7.1.0 → 7.3.0

package/dist/cli/command-registry.js

@@ -1,3 +1,4 @@
+import { COMMAND_MANIFEST_BY_NAME, commandManifestNames } from './command-manifest-lite.js';
 const SAFE_COMMAND_CONTRACT = {
     risk: 'R2',
     latency: 'normal',
@@ -26,6 +27,10 @@ function pickRunner(mod) {
     }
     return null;
 }
+function usageOf(mod) {
+    const candidate = mod?.usage;
+    return typeof candidate === 'function' ? { usage: candidate } : {};
+}
 function normalizeCommandModule(moduleValue, _packageRequiredFile) {
     if (!moduleValue || typeof moduleValue !== 'object')
         throw new Error('Invalid command module');
@@ -35,6 +40,7 @@ function normalizeCommandModule(moduleValue, _packageRequiredFile) {
         throw new Error('Command module must export run/main/default callable');
     return {
         run: async (command, args) => runner(command, args),
+        ...usageOf(rec),
     };
 }
 export function directCommand(loader, packageRequiredFile) {
@@ -44,21 +50,21 @@ export function argsCommand(loader, exportName, packageRequiredFile) {
     return async () => {
         const mod = await loader();
         const fn = functionExport(mod, exportName);
-        return { run: (_command, args) => fn(args) };
+        return { run: (_command, args) => fn(args), ...usageOf(mod) };
     };
 }
 function noArgsCommand(loader, exportName, packageRequiredFile) {
     return async () => {
         const mod = await loader();
         const fn = functionExport(mod, exportName);
-        return { run: () => fn() };
+        return { run: () => fn(), ...usageOf(mod) };
     };
 }
 function commandArgsCommand(loader, exportName, packageRequiredFile) {
     return async () => {
         const mod = await loader();
         const fn = functionExport(mod, exportName);
-        return { run: (command, args) => fn(command, args) };
+        return { run: (command, args) => fn(command, args), ...usageOf(mod) };
     };
 }
 function subcommand(loader, exportName, packageRequiredFile, fallbackSubcommand) {
@@ -70,6 +76,7 @@ function subcommand(loader, exportName, packageRequiredFile, fallbackSubcommand)
                 const [subcommandName = fallbackSubcommand, ...rest] = args;
                 return fn(subcommandName ?? '', rest);
             },
+            ...usageOf(mod),
         };
     };
 }
@@ -109,6 +116,31 @@ function applyCommandContractOverrides(commands, overrides) {
     }
     return commands;
 }
+function applyCommandManifestContract(commands) {
+    const definitionNames = Object.keys(commands).sort();
+    const manifestNames = commandManifestNames();
+    if (JSON.stringify(definitionNames) !== JSON.stringify(manifestNames)) {
+        throw new Error(`Command manifest/registry mismatch: registry=${definitionNames.join(',')} manifest=${manifestNames.join(',')}`);
+    }
+    for (const name of manifestNames) {
+        const command = commands[name];
+        const manifest = COMMAND_MANIFEST_BY_NAME[name];
+        if (!command || !manifest)
+            throw new Error(`Missing command manifest metadata for ${name}`);
+        Object.assign(command, {
+            maturity: manifest.maturity,
+            summary: manifest.summary,
+            risk: manifest.risk,
+            latency: manifest.latency,
+            supportsJson: manifest.supportsJson,
+            remoteAllowed: manifest.remoteAllowed,
+            telegramAllowed: manifest.telegramAllowed,
+            inputProfile: manifest.inputProfile,
+            requiredCapabilities: [...manifest.requiredCapabilities]
+        });
+    }
+    return commands;
+}
 const COMMAND_DEFINITIONS = {
     help: readOnly(entry('stable', 'Show SKS help', 'dist/commands/help.js', directCommand(() => import('../commands/help.js'), 'dist/commands/help.js'))),
     version: readOnly(entry('stable', 'Show SKS version', 'dist/commands/version.js', directCommand(() => import('../commands/version.js'), 'dist/commands/version.js'))),
@@ -150,12 +182,12 @@ const COMMAND_DEFINITIONS = {
     rollback: activeRouteDiagnostic(entry('beta', 'List or apply managed-path rollback actions', 'dist/core/commands/rollback-command.js', argsCommand(() => import('../core/commands/rollback-command.js'), 'rollbackCommand', 'dist/core/commands/rollback-command.js'))),
     postinstall: skipMigrationGate(entry('stable', 'Run postinstall bootstrap', 'dist/core/commands/basic-cli.js', basicArgs('postinstallCommand'))),
     codex: skipMigrationGate(entry('beta', 'Check Codex CLI compatibility and vendored hook schemas', 'dist/commands/codex.js', directCommand(() => import('../commands/codex.js'), 'dist/commands/codex.js'))),
-    'codex-app': entry('beta', 'Check Codex App readiness', 'dist/commands/codex-app.js', directCommand(() => import('../commands/codex-app.js'), 'dist/commands/codex-app.js')),
+    'codex-app': skipMigrationGate(entry('beta', 'Check Codex App readiness', 'dist/commands/codex-app.js', directCommand(() => import('../commands/codex-app.js'), 'dist/commands/codex-app.js'))),
     'codex-native': entry('beta', 'Inspect Codex Native broker and routing readiness', 'dist/commands/codex-native.js', directCommand(() => import('../commands/codex-native.js'), 'dist/commands/codex-native.js')),
-    'codex-lb': entry('beta', 'Inspect codex-lb status and circuit health', 'dist/commands/codex-lb.js', directCommand(() => import('../commands/codex-lb.js'), 'dist/commands/codex-lb.js')),
+    'codex-lb': skipMigrationGate(entry('beta', 'Inspect codex-lb status and circuit health', 'dist/commands/codex-lb.js', directCommand(() => import('../commands/codex-lb.js'), 'dist/commands/codex-lb.js'))),
     menubar: activeRouteDiagnostic(entry('beta', 'Inspect/install/restart/uninstall SKS menu bar', 'dist/core/commands/menubar-command.js', subcommand(() => import('../core/commands/menubar-command.js'), 'menubarCommand', 'dist/core/commands/menubar-command.js', 'status'))),
     remote: entry('beta', 'Inspect official Remote readiness and run the proof-aware SSH stdio worker', 'dist/core/commands/remote-command.js', argsCommand(() => import('../core/commands/remote-command.js'), 'remoteCommand', 'dist/core/commands/remote-command.js')),
-    telegram: entry('beta', 'Inspect and run the private proof-aware Telegram Hub', 'dist/core/commands/telegram-command.js', argsCommand(() => import('../core/commands/telegram-command.js'), 'telegramCommand', 'dist/core/commands/telegram-command.js')),
+    telegram: entry('beta', 'Pair and run the private local Codex Telegram Hub', 'dist/core/commands/telegram-command.js', argsCommand(() => import('../core/commands/telegram-command.js'), 'telegramCommand', 'dist/core/commands/telegram-command.js')),
     hooks: skipMigrationGate(entry('beta', 'Explain and inspect Codex hooks', 'dist/commands/hooks.js', directCommand(() => import('../commands/hooks.js'), 'dist/commands/hooks.js'))),
     'zellij-lane': entry('beta', 'Render a Zellij lane frame for SKS sessions', 'dist/commands/zellij-lane.js', directCommand(() => import('../commands/zellij-lane.js'), 'dist/commands/zellij-lane.js')),
     'zellij-slot-pane': entry('beta', 'Render a compact Zellij worker slot pane', 'dist/commands/zellij-slot-pane.js', directCommand(() => import('../commands/zellij-slot-pane.js'), 'dist/commands/zellij-slot-pane.js')),
@@ -183,6 +215,7 @@ const COMMAND_DEFINITIONS = {
     'computer-use': routeStateMutator(entry('beta', 'Record native Mac/non-web Computer Use visual evidence', 'dist/core/commands/computer-use-command.js', commandArgsCommand(() => import('../core/commands/computer-use-command.js'), 'computerUseCommand', 'dist/core/commands/computer-use-command.js')), ['computer-use-gate.json']),
     context7: entry('beta', 'Context7 checks and docs', 'dist/cli/context7-command.js', subcommand(() => import('./context7-command.js'), 'context7Command', 'dist/cli/context7-command.js', 'check')),
     'super-search': entry('beta', 'Run Super-Search provider-independent source intelligence', 'dist/cli/super-search-command.js', subcommand(() => import('./super-search-command.js'), 'superSearchCommand', 'dist/cli/super-search-command.js', 'doctor')),
+    search: readOnly(entry('beta', 'Local files/text/structure/symbol/context search engines', 'dist/commands/search.js', subcommand(() => import('../commands/search.js'), 'run', 'dist/commands/search.js', 'status'))),
     recallpulse: entry('labs', 'RecallPulse evidence route', 'dist/commands/recallpulse.js', directCommand(() => import('../commands/recallpulse.js'), 'dist/commands/recallpulse.js')),
     pipeline: activeRouteDiagnostic(entry('beta', 'Inspect pipeline missions', 'dist/commands/pipeline.js', directCommand(() => import('../commands/pipeline.js'), 'dist/commands/pipeline.js'))),
     guard: entry('beta', 'Check harness guard', 'dist/commands/guard.js', directCommand(() => import('../commands/guard.js'), 'dist/commands/guard.js')),
@@ -192,7 +225,7 @@ const COMMAND_DEFINITIONS = {
     aliases: entry('stable', 'Show command aliases', 'dist/core/commands/basic-cli.js', basicNoArgs('aliasesCommand')),
     selftest: entry('stable', 'Run local mock selftest', 'dist/core/commands/basic-cli.js', basicArgs('selftestCommand')),
     goal: entry('beta', 'Print stateless Codex native Goal controls', 'dist/core/commands/goal-command.js', subcommand(() => import('../core/commands/goal-command.js'), 'goalCommand', 'dist/core/commands/goal-command.js')),
-    'seo-geo-optimizer': entry('beta', 'Run unified SEO/GEO optimizer audit/plan/apply/verify on the search-visibility kernel', 'dist/core/commands/seo-command.js', argsCommand(() => import('../core/commands/seo-command.js'), 'seoGeoOptimizerCommand', 'dist/core/commands/seo-command.js')),
+    'seo-geo-optimizer': entry('beta', 'Run unified SEO/GEO optimizer audit/plan/apply/verify plus research/strategy (--include-marketing) on the search-visibility kernel', 'dist/core/commands/seo-command.js', argsCommand(() => import('../core/commands/seo-command.js'), 'seoGeoOptimizerCommand', 'dist/core/commands/seo-command.js')),
     hook: skipMigrationGate(entry('beta', 'Codex hook entrypoint', 'dist/commands/hook.js', directCommand(() => import('../commands/hook.js'), 'dist/commands/hook.js'))),
     profile: entry('labs', 'Inspect/set profile', 'dist/commands/profile.js', directCommand(() => import('../commands/profile.js'), 'dist/commands/profile.js')),
     hproof: entry('beta', 'Evaluate H-Proof gate', 'dist/commands/hproof.js', directCommand(() => import('../commands/hproof.js'), 'dist/commands/hproof.js')),
@@ -222,7 +255,7 @@ const COMMAND_DEFINITIONS = {
     }),
     'agent-bridge': readOnly(entry('beta', 'Publish the agent-bridge manifest and print host registration snippets for external agent systems', 'dist/core/commands/agent-bridge-command.js', subcommand(() => import('../core/commands/agent-bridge-command.js'), 'agentBridgeCommand', 'dist/core/commands/agent-bridge-command.js', 'setup')))
 };
-export const COMMANDS = applyCommandContractOverrides(COMMAND_DEFINITIONS, {
+const COMMANDS_WITH_LEGACY_CONTRACT_OVERRIDES = applyCommandContractOverrides(COMMAND_DEFINITIONS, {
     autoresearch: { latency: 'long' },
     bench: { latency: 'long' },
     check: { risk: 'R1', latency: 'long' },
@@ -294,6 +327,7 @@ export const COMMANDS = applyCommandContractOverrides(COMMAND_DEFINITIONS, {
         requiredCapabilities: ['proof.artifacts']
     }
 });
+export const COMMANDS = applyCommandManifestContract(COMMANDS_WITH_LEGACY_CONTRACT_OVERRIDES);
 export const TYPED_COMMANDS = COMMANDS;
 export const LEGACY_COMMAND_ALIASES = {};
 export const COMMAND_ALIASES = {

package/dist/cli/help.js

@@ -0,0 +1,30 @@
+export function isHelpRequest(args) {
+    return args.includes('--help')
+        || args.includes('-h')
+        || String(args[0] || '').toLowerCase() === 'help';
+}
+export function renderManifestHelp(command, entry) {
+    if (!entry)
+        return `Usage: sks ${command}\n\nNo manifest entry is registered for this command.`;
+    const lines = [`Usage: sks ${entry.name} [options]`, '', entry.summary];
+    const notes = [];
+    if (entry.deprecated)
+        notes.push('deprecated — kept only for compatibility');
+    if (entry.maturity !== 'stable')
+        notes.push(`maturity: ${entry.maturity}`);
+    if (entry.readonly)
+        notes.push('read-only: does not mutate project or Codex state');
+    if (entry.diagnostic)
+        notes.push('diagnostic');
+    notes.push(`risk: ${entry.risk}`, `latency: ${entry.latency}`);
+    lines.push('', ...notes.map((note) => `  ${note}`));
+    const flags = ['  --help, -h    Print this usage without running the command.'];
+    if (entry.supportsJson)
+        flags.push('  --json        Emit the machine-readable result.');
+    lines.push('', 'Options:', ...flags);
+    lines.push('', 'Run `sks commands` for the full command list.');
+    return lines.join('\n');
+}
+export function helpResult(command) {
+    return { ok: true, status: 'help', action: 'help', command };
+}

package/dist/cli/install-helpers-codex-lb-config.js

@@ -6,6 +6,7 @@ import { openRouterSecretPaths, resolveOpenRouterApiKey } from '../core/provider
 import { reconcileRetiredSksConfigText } from '../core/auto-review.js';
 import { removeTopLevelTomlKeyIfValue, safeWriteCodexConfigToml, upsertTopLevelTomlString, upsertTomlTable } from '../core/codex-runtime/codex-desktop-config-policy.js';
 import { codexLbConfigPath, normalizeCodexLbBaseUrl } from './install-helpers-codex-lb-shared.js';
+import { escapeRegExp } from '../core/text/regex.js';
 export function upsertCodexLbConfig(text = '', baseUrl, selectDefault = true) {
     let next = selectDefault
         ? upsertTopLevelTomlString(text, 'model_provider', 'codex-lb')
@@ -140,7 +141,11 @@ export async function ensureStoredOpenRouterProviderDuringInstall(opts = {}) {
         home,
         env
     });
-    const ok = repair?.ok !== false;
+    const configPath = repair?.config_path || opts.configPath || codexLbConfigPath(home);
+    const { ensureOpenRouterModelCatalog } = await import('../core/codex-app/openrouter-model-catalog.js');
+    const catalogRepair = await ensureOpenRouterModelCatalog({ configPath, home, env })
+        .catch((err) => ({ ok: false, status: 'failed', error: err?.message || String(err) }));
+    const ok = repair?.ok !== false && catalogRepair?.ok !== false;
     return {
         schema: 'sks.openrouter-provider-upgrade-repair.v1',
         ok,
@@ -148,11 +153,12 @@ export async function ensureStoredOpenRouterProviderDuringInstall(opts = {}) {
         reason: ok ? 'stored_openrouter_key_provider_reconciled' : 'stored_openrouter_key_provider_repair_failed',
         key_present: true,
         key_source: key.source,
-        config_path: repair?.config_path || opts.configPath || codexLbConfigPath(home),
+        config_path: configPath,
         provider: GLM_CODEX_CONFIG_PROVIDER_ID,
         blockers: ok ? [] : ['openrouter_provider_repair_failed'],
         warnings: key.warnings,
-        repair
+        repair,
+        model_catalog_repair: catalogRepair
     };
 }
 export function detectCodexLbSetupDrift(state = {}) {
@@ -263,9 +269,6 @@ export async function sha256Text(value = '') {
     const { createHash } = await import('node:crypto');
     return createHash('sha256').update(String(value || '')).digest('hex');
 }
-function escapeRegExp(value) {
-    return String(value).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-}
 function topLevelTomlString(text = '', key) {
     const topLevel = String(text || '').split(/\n\s*\[/)[0] || '';
     return topLevel.match(new RegExp(`(^|\\n)\\s*${escapeRegExp(key)}\\s*=\\s*"([^"]+)"\\s*(?:#.*)?(?=\\n|$)`))?.[2] || '';

package/dist/cli/install-helpers-codex-lb-selftest-chain.js

@@ -97,7 +97,7 @@ export async function runCodexLbLaunchChainSelftest(input) {
     const survivingLegacy = legacyStamps.filter((stamp) => codexLbConfig.includes(stamp));
     const stableCapabilityStamps = ['computer_use = true', 'browser_use = true', 'browser_use_external = true', 'image_generation = true', 'in_app_browser = true', 'guardian_approval = true', 'tool_suggest = true', 'plugins = true'];
     const missingStableCapabilities = stableCapabilityStamps.filter((stamp) => !codexLbConfig.includes(stamp));
-    if (!codexLbConfig.includes('hooks = true') || hasDeprecatedCodexHooksFeatureFlag(codexLbConfig) || !codexLbConfig.includes('multi_agent = true') || !codexLbConfig.includes('fast_mode = true') || !codexLbConfig.includes('apps = true') || survivingLegacy.length || missingStableCapabilities.length || !/\[profiles\.custom\][\s\S]*?model_reasoning_effort = "low"/.test(codexLbConfig) || hasTopLevelCodexModeLock(codexLbConfig))
+    if (!codexLbConfig.includes('hooks = true') || hasDeprecatedCodexHooksFeatureFlag(codexLbConfig) || /(?:^|\n)\s*multi_agent\s*=/.test(codexLbConfig) || !codexLbConfig.includes('fast_mode = true') || !codexLbConfig.includes('apps = true') || survivingLegacy.length || missingStableCapabilities.length || !/\[profiles\.custom\][\s\S]*?model_reasoning_effort = "low"/.test(codexLbConfig) || hasTopLevelCodexModeLock(codexLbConfig))
         throw new Error(`selftest: codex-lb setup did not enforce the current feature-flag contract${survivingLegacy.length ? ` — surviving legacy stamps: ${survivingLegacy.join(', ')}` : ''}${missingStableCapabilities.length ? ` — missing stable capabilities: ${missingStableCapabilities.join(', ')}` : ''}`);
     if (!hasCodexUnstableFeatureWarningSuppression(codexLbConfig))
         throw new Error('selftest: codex-lb setup did not suppress Codex unstable feature warning');

package/dist/cli/install-helpers-install-support.js

@@ -13,7 +13,7 @@ import { context7ConfigToml, DOLLAR_SKILL_NAMES, GETDESIGN_REFERENCE, hasContext
 import { checkZellijCapability } from '../core/zellij/zellij-capability.js';
 import { reconcileCodexAppUpgradeProcesses } from '../core/codex-app.js';
 import { restartCodexApp } from '../core/codex-app/codex-app-restart.js';
-import { cleanupMacLaunchSecretEnvironment } from '../core/codex-app/sks-menubar.js';
+import { cleanupMacLaunchSecretEnvironment } from '../core/codex-app/menubar/index.js';
 import { recordCodexLbHealthEvent } from '../core/codex-lb-circuit.js';
 import { loadCodexLbEnv, writeCodexLbKeychain, codexLbMetadataPath } from '../core/codex-lb/codex-lb-env.js';
 import { codexLbToolCatalogPath, ensureCodexLbToolCatalog } from '../core/codex-lb/codex-lb-tool-catalog.js';

package/dist/cli/install-helpers.js

@@ -13,7 +13,7 @@ import { context7ConfigToml, DOLLAR_SKILL_NAMES, GETDESIGN_REFERENCE, hasContext
 import { checkZellijCapability } from '../core/zellij/zellij-capability.js';
 import { reconcileCodexAppUpgradeProcesses } from '../core/codex-app.js';
 import { restartCodexApp } from '../core/codex-app/codex-app-restart.js';
-import { cleanupMacLaunchSecretEnvironment } from '../core/codex-app/sks-menubar.js';
+import { cleanupMacLaunchSecretEnvironment } from '../core/codex-app/menubar/index.js';
 import { recordCodexLbHealthEvent } from '../core/codex-lb-circuit.js';
 import { loadCodexLbEnv, writeCodexLbKeychain, codexLbMetadataPath } from '../core/codex-lb/codex-lb-env.js';
 import { codexLbToolCatalogPath, ensureCodexLbToolCatalog } from '../core/codex-lb/codex-lb-tool-catalog.js';
@@ -29,6 +29,7 @@ import { checkCodexLbResponseChain } from './install-helpers-codex-lb-chain.js';
 import { CODEX_LB_CANONICAL_FAST_SERVICE_TIER, CODEX_LB_PROVIDER_ENV_KEY, CODEX_LB_PROVIDER_NAME, askPostinstallQuestion, codexAuthChatgptBackupPath, codexAuthPath, codexLbConfigPath, codexLbEnvPath, hasTopLevelCodexLbSelected, normalizeCodexLbBaseUrl, parseCodexLbEnvKey, redactSecretText } from './install-helpers-codex-lb-shared.js';
 import { appliedCodexLbPersistenceModes, captureCodexLbSetupWriteState, codexLbSharedOpenAiRoutingState, detectCodexLbSetupDrift, ensureGlobalCodexAppGlmProfile, ensureStoredOpenRouterProviderDuringInstall, parseCodexLbEnvBaseUrl, parseCodexSharedLoginApiKey, removeCodexLbSharedOpenAiRouting, sha256Text, shellSingleQuote, upsertCodexAppGlmConfig, upsertCodexLbConfig, upsertCodexLbSharedOpenAiRouting } from './install-helpers-codex-lb-config.js';
 import { ensureCodexImagegenDuringInstall, ensureGlobalCodexSkillsDuringInstall, ensureGlobalContext7DuringInstall, ensureGlobalGetdesignSkillDuringInstall, ensureSksCommandDuringInstall } from './install-helpers-install-support.js';
+import { escapeRegExp } from '../core/text/regex.js';
 function packagedSksEntrypoint() {
     return path.join(packageRoot(), 'dist', 'bin', 'sks.js');
 }
@@ -393,7 +394,14 @@ async function ensureCodexLbToolCatalogSelection(input, opts = {}) {
     const selected = hasTopLevelCodexLbSelected(current);
     const canBindCatalog = selected || opts.allowUnselectedCatalogWrite === true;
     const existingCatalogPath = topLevelTomlString(current, 'model_catalog_json');
-    if (canBindCatalog && existingCatalogPath && path.resolve(existingCatalogPath) !== path.resolve(catalogPath)) {
+    const { isSksManagedCatalogPath, resolveCatalogPath } = await import('../core/codex-app/multi-provider-router-support.js');
+    const existingCatalogResolved = existingCatalogPath
+        ? resolveCatalogPath(existingCatalogPath, { home: input.home, configPath: input.configPath })
+        : null;
+    const existingCatalogReplaceable = !existingCatalogResolved
+        || (isSksManagedCatalogPath(existingCatalogResolved, { home: input.home })
+            && (selected || opts.willSelectProvider === true));
+    if (canBindCatalog && existingCatalogResolved && existingCatalogResolved !== path.resolve(catalogPath) && !existingCatalogReplaceable) {
         return {
             schema: 'sks.codex-lb-tool-catalog-selection.v1',
             ok: false,
@@ -535,7 +543,7 @@ export async function configureCodexLb(opts = {}) {
     }
     process.env.CODEX_LB_BASE_URL = baseUrl;
     process.env.CODEX_LB_API_KEY = apiKey;
-    let toolCatalog = await ensureCodexLbToolCatalogSelection({ home, configPath, baseUrl, apiKey }, { ...opts, allowUnselectedCatalogWrite: true });
+    let toolCatalog = await ensureCodexLbToolCatalogSelection({ home, configPath, baseUrl, apiKey }, { ...opts, allowUnselectedCatalogWrite: true, willSelectProvider: useDefaultProvider === true });
     if (toolCatalog.config_changed || toolCatalog.status === 'repaired' || toolCatalog.status === 'cached_compatible') {
         appliedActions.push({ type: 'write_model_tool_catalog', target: toolCatalog.path, ok: toolCatalog.ok === true, status: toolCatalog.status });
     }
@@ -948,9 +956,14 @@ export async function repairCodexLbAuth(opts = {}) {
             status = await codexLbStatus({ ...opts, probeToolOutputRecovery: true });
         }
     }
-    if (status.env_key_configured && status.base_url && (!status.provider_contract_ok || !status.selected || legacyAuthMigrated || hasTopLevelCodexModeLock(currentConfig) || (opts.forceCodexLbApiKeyAuth === true && !status.ok))) {
+    const repairCurrentProvider = topLevelTomlString(currentConfig, 'model_provider');
+    const repairPreserveThirdParty = Boolean(repairCurrentProvider)
+        && repairCurrentProvider !== 'codex-lb'
+        && opts.forceCodexLbApiKeyAuth !== true
+        && opts.authMode !== 'codex-lb';
+    if (status.env_key_configured && status.base_url && (!status.provider_contract_ok || (!status.selected && !repairPreserveThirdParty) || legacyAuthMigrated || hasTopLevelCodexModeLock(currentConfig) || (opts.forceCodexLbApiKeyAuth === true && !status.ok))) {
         await ensureDir(path.dirname(status.config_path));
-        let next = upsertCodexLbConfig(currentConfig, status.base_url);
+        let next = upsertCodexLbConfig(currentConfig, status.base_url, !repairPreserveThirdParty);
         next = normalizeCodexFastModeUiConfig(next, {
             forceFastMode: opts.forceFastMode === true || opts.forceCodexLbApiKeyAuth === true
         });
@@ -1467,7 +1480,7 @@ export async function unselectCodexLbProvider(opts = {}) {
     if (!hasTopLevelCodexLbSelected(current) && !managedCatalogSelected && !managedSharedOpenAiRouting)
         return { ok: true, status: 'not_selected', config_path: configPath };
     try {
-        let next = removeTopLevelTomlString(current, 'model_provider');
+        let next = removeTopLevelTomlKeyIfValue(current, 'model_provider', 'codex-lb');
         next = removeTopLevelTomlKeyIfValue(next, 'model_catalog_json', managedCatalogPath);
         const routingRemoval = removeCodexLbSharedOpenAiRouting(next, providerBaseUrl);
         next = routingRemoval.text;
@@ -1936,6 +1949,3 @@ export { askPostinstallQuestion, codexLbConfigPath, codexLbEnvPath, normalizeCod
 export { ensureGlobalCodexAppGlmProfile, ensureStoredOpenRouterProviderDuringInstall, upsertCodexAppGlmConfig, upsertCodexLbConfig } from './install-helpers-codex-lb-config.js';
 export { checkCodexLbResponseChain } from './install-helpers-codex-lb-chain.js';
 export { selftestCodexLb } from './install-helpers-codex-lb-selftest.js';
-function escapeRegExp(value) {
-    return String(value).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-}

package/dist/cli/router.js

@@ -1,4 +1,6 @@
 import { COMMAND_ALIASES_LITE, COMMAND_MANIFEST_BY_NAME, COMMAND_NAME_SET, } from './command-manifest-lite.js';
+import { ui as cliUi } from './cli-theme.js';
+import { helpResult, isHelpRequest, renderManifestHelp } from './help.js';
 import { findRetiredGlobalExecutionArgumentErrors } from './global-mode-router.js';
 export function isCommandName(value) {
     return COMMAND_NAME_SET.has(value);
@@ -121,13 +123,18 @@ async function dispatchInner(argv) {
     const { COMMANDS } = await import('./command-registry.js');
     const commandEntry = COMMANDS[command];
     const mod = await commandEntry.lazy();
+    if (helpRequest) {
+        cliUi.banner(`${rawCommand || command} help`);
+        cliUi.ok('usage only — the command was not run');
+        console.log(typeof mod.usage === 'function'
+            ? mod.usage(rawCommand || command)
+            : renderManifestHelp(command, entry));
+        return helpResult(command);
+    }
     if (typeof mod.run !== 'function')
         throw new Error(`Command ${command} must export run(command, args)`);
     return mod.run(rawCommand || command, rest);
 }
-function isHelpRequest(args) {
-    return args.includes('--help') || args.includes('-h') || String(args[0] || '').toLowerCase() === 'help';
-}
 async function ensureActiveRouteCommandGate(command, args) {
     const entry = COMMAND_MANIFEST_BY_NAME[command];
     if (command === 'route' || entry.readonly === true || entry.allowedDuringActiveRoute === true && entry.mutatesRouteState !== true) {
@@ -202,6 +209,12 @@ export function safeReadOnlySubcommand(command, args) {
     if (command === 'remote' && ['readiness', 'status', 'show'].includes(sub)) {
         return !args.some((arg) => ['--fix', '--yes', '-y', '--write', '--apply', '--execute', '--force', '--real'].includes(String(arg)));
     }
+    if (command === 'remote' && ['machines', 'machine'].includes(sub) && ['list', 'validate'].includes(nested)) {
+        return !args.some((arg) => ['--fix', '--yes', '-y', '--write', '--apply', '--execute', '--force', '--real'].includes(String(arg)));
+    }
+    if (command === 'telegram' && (sub === 'validate-config' || (sub === 'hub' && nested === 'status'))) {
+        return !args.some((arg) => ['--fix', '--yes', '-y', '--write', '--apply', '--execute', '--force', '--real'].includes(String(arg)));
+    }
     if (!['status', 'show', 'list', 'observe', 'watch', 'doctor', 'help'].includes(sub))
         return false;
     return !args.some((arg) => ['--fix', '--yes', '-y', '--write', '--apply', '--execute', '--force', '--real'].includes(String(arg)));

package/dist/commands/codex-app.js

@@ -11,11 +11,11 @@ import { buildCodexHookLifecycle } from '../core/codex-app/codex-hook-lifecycle.
 import { resolveCodexAppExecutionProfile } from '../core/codex-app/codex-app-execution-profile.js';
 import { repairCodexNativeManagedAssets } from '../core/codex-native/codex-native-repair-transaction.js';
 import { doctorCodexAppGlmProfile, installCodexAppGlmProfile } from '../core/codex-app/glm-profile-installer.js';
-import { openRouterStatus, useOpenRouter } from '../core/codex-app/openrouter-activate.js';
-import { OPENROUTER_DEFAULT_MODEL } from '../core/codex-app/openrouter-provider.js';
+import { openRouterStatus, restoreDesktopRoutingSnapshot, useOpenRouter } from '../core/codex-app/openrouter-activate.js';
 import { promptForOpenRouterKeyHidden, writeStoredOpenRouterKey } from '../core/providers/openrouter/openrouter-secret-store.js';
 import { compactOpenRouterModelsResult, listOpenRouterModels, testOpenRouterConnection } from '../core/providers/openrouter/openrouter-account.js';
 import { restartCodexApp } from '../core/codex-app/codex-app-restart.js';
+import { MULTI_PROVIDER_ROUTER_DEFAULT_BASE_URL, multiProviderRouterStatus, testMultiProviderRouter, useMultiProviderRouter } from '../core/codex-app/multi-provider-router.js';
 import { resetRoleModelPreference, roleModelPreferencesStatus, setRoleModelPreference } from '../core/subagents/role-model-preferences.js';
 export async function run(_command, args = []) {
     const action = args[0] || 'check';
@@ -72,11 +72,19 @@ export async function run(_command, args = []) {
     }
     if (action === 'use-openrouter' || action === 'use-or') {
         const root = await sksRoot();
-        const model = readOption(args, '--model', OPENROUTER_DEFAULT_MODEL);
+        const model = readOption(args, '--model', '');
         const result = await useOpenRouter({
             root,
             model,
-            restartApp: flag(args, '--restart-app') || flag(args, '--restart') || !flag(args, '--no-restart-app')
+            restartApp: flag(args, '--restart-app') || flag(args, '--restart') || !flag(args, '--no-restart-app'),
+            preserveThreadSidebar: !flag(args, '--no-preserve-thread-sidebar')
+        });
+        return printCodexAppResult(args, result);
+    }
+    if (action === 'restore-desktop-routing' || action === 'restore-previous-provider') {
+        const result = await restoreDesktopRoutingSnapshot({
+            restartApp: flag(args, '--restart-app') || flag(args, '--restart') || !flag(args, '--no-restart-app'),
+            restartImpl: restartCodexApp
         });
         return printCodexAppResult(args, result);
     }
@@ -93,12 +101,39 @@ export async function run(_command, args = []) {
         const result = await testOpenRouterConnection({ model: readOption(args, '--model', '') });
         return printCodexAppResult(args, result);
     }
+    if (action === 'router-status' || action === 'multi-provider-status' || action === 'opencodex-status') {
+        const result = await multiProviderRouterStatus({
+            baseUrl: readOption(args, '--base-url', ''),
+            catalogPath: readOption(args, '--catalog', '')
+        });
+        return printCodexAppResult(args, result);
+    }
+    if (action === 'router-test' || action === 'multi-provider-test' || action === 'opencodex-test') {
+        const result = await testMultiProviderRouter({
+            baseUrl: readOption(args, '--base-url', MULTI_PROVIDER_ROUTER_DEFAULT_BASE_URL),
+            catalogPath: readOption(args, '--catalog', ''),
+            model: readOption(args, '--model', '')
+        });
+        return printCodexAppResult(args, result);
+    }
+    if (action === 'use-router' || action === 'use-multi-provider' || action === 'use-opencodex') {
+        const result = await useMultiProviderRouter({
+            model: readOption(args, '--model', ''),
+            baseUrl: readOption(args, '--base-url', MULTI_PROVIDER_ROUTER_DEFAULT_BASE_URL),
+            catalogPath: readOption(args, '--catalog', ''),
+            replaceCatalog: flag(args, '--replace-catalog'),
+            forceRoutingOverride: flag(args, '--force-routing-override'),
+            restartApp: flag(args, '--restart-app') || flag(args, '--restart') || !flag(args, '--no-restart-app')
+        });
+        return printCodexAppResult(args, result);
+    }
     if (action === 'role-models') {
         return printCodexAppResult(args, await roleModelPreferencesStatus());
     }
     if (action === 'set-role-model') {
         const result = await setRoleModelPreference({
             role: readOption(args, '--role', ''),
+            provider: readOption(args, '--provider', ''),
             model: readOption(args, '--model', ''),
             reasoning: readOption(args, '--reasoning', '')
         });
@@ -168,7 +203,7 @@ export async function run(_command, args = []) {
             process.exitCode = 1;
         return;
     }
-    console.error('Usage: sks codex-app check|status|harness-matrix|skill-sync|agent-role-sync|init-deep|hook-lifecycle|execution-profile|set-openrouter-key [--api-key-stdin]|use-openrouter --model <id>|openrouter-status|openrouter-models [--ids-only]|openrouter-test [--model <id>]|role-models|set-role-model --role <name> --model <id> --reasoning <effort>|reset-role-model --role <name>|product-design [--check-only]|ensure-product-design|chrome-extension|pat status|remote-control [--json]');
+    console.error('Usage: sks codex-app check|status|harness-matrix|skill-sync|agent-role-sync|init-deep|hook-lifecycle|execution-profile|set-openrouter-key [--api-key-stdin]|use-openrouter --model <id>|restore-desktop-routing|openrouter-status|openrouter-models [--ids-only]|openrouter-test [--model <id>]|router-status [--base-url <loopback-url>] [--catalog <path>]|router-test --model <provider/model> [--base-url <loopback-url>] [--catalog <path>]|use-router --model <provider/model> [--base-url <loopback-url>] [--catalog <path>] [--replace-catalog] [--force-routing-override]|role-models|set-role-model --role <name> [--provider <id>] --model <catalog-slug> --reasoning <effort>|reset-role-model --role <name>|product-design [--check-only]|ensure-product-design|chrome-extension|pat status|remote-control [--json]');
     console.error('Note: glm-profile is retired (strips leftover Desktop GLM profiles); use set-openrouter-key / use-openrouter.');
     process.exitCode = 1;
 }

package/dist/commands/doctor-profile.js

@@ -0,0 +1,78 @@
+import { flag } from '../cli/args.js';
+import { sksMenuBarRestartDeferred } from '../core/codex-app/menubar/index.js';
+export function doctorProfileFromArgs(args = [], doctorFix = false) {
+    const explicit = readOption(args, '--profile');
+    if (isDoctorProfile(explicit))
+        return explicit;
+    if (flag(args, '--full'))
+        return 'full';
+    if (flag(args, '--capabilities'))
+        return 'capabilities';
+    return doctorFix ? 'fix' : 'fast';
+}
+export function doctorArgWarnings(args = []) {
+    const warnings = [];
+    const explicit = readOption(args, '--profile');
+    if (explicit && !isDoctorProfile(explicit)) {
+        warnings.push(`unknown_profile:${explicit}; supported profiles: migration, full, capabilities, fast, fix`);
+    }
+    for (const value of unknownDoctorFlags(args))
+        warnings.push(`unknown_flag:${value}`);
+    return warnings;
+}
+export function doctorMenuBarInstallPolicy(args = [], doctorFix = false, env = process.env) {
+    const profile = doctorProfileFromArgs(args, doctorFix);
+    const phaseEnabled = doctorPhaseIdsForProfile(profile).includes('sks_menubar');
+    const apply = doctorFix && phaseEnabled;
+    return {
+        profile,
+        phase_enabled: phaseEnabled,
+        apply,
+        launch: apply && !sksMenuBarRestartDeferred(env)
+    };
+}
+export function doctorPhaseIdsForProfile(profile) {
+    const required = [
+        'codex_startup_repair',
+        'startup_config_repair',
+        'context7_repair',
+        'context7_mcp_repair',
+        'hook_trust_repair',
+        'command_alias_cleanup'
+    ];
+    if (profile === 'migration')
+        return required;
+    const optional = ['supabase_mcp_repair', 'native_capability_repair', 'sks_menubar'];
+    if (profile === 'full' || profile === 'capabilities')
+        return ['setup', ...required, ...optional];
+    return [...required, ...optional];
+}
+function unknownDoctorFlags(args) {
+    const knownBoolean = new Set([
+        '--fix', '--yes', '-y', '--machine-only', '--actual-codex', '--require-actual-codex',
+        '--full', '--capabilities', '--repair-codex-app-ui', '--repair-zellij', '--install-homebrew',
+        '--repair-native-capabilities', '--repair-codex-native', '--local-only', '--global-only', '--project', '--global',
+        '--dry-run', '--json'
+    ]);
+    const knownValue = new Set(['--profile', '--report-file', '--codex-bin', '--install-scope']);
+    const unknown = [];
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = String(args[index] || '');
+        if (!arg.startsWith('-'))
+            continue;
+        if (knownValue.has(arg)) {
+            index += 1;
+            continue;
+        }
+        if (!knownBoolean.has(arg))
+            unknown.push(arg);
+    }
+    return unknown;
+}
+function isDoctorProfile(value) {
+    return ['migration', 'full', 'capabilities', 'fast', 'fix'].includes(String(value || ''));
+}
+function readOption(args, name) {
+    const index = args.indexOf(name);
+    return index >= 0 && args[index + 1] ? String(args[index + 1]) : null;
+}